# The HTTP API

GET the base address to list the tools open to you. POST a tool's input as JSON to run it. Send your key as a bearer token.

v1 · OpenAPI 3.1 · JSON

## The address

```text
https://pirateskills.com/api/public/agent/v1/tools

# the same door, unversioned
https://pirateskills.com/api/public/agent/tools
```

The version is in the address. Within v1 we only add; see [Versions](https://pirateskills.com/docs/versions).

## List the tools – no key

A visitor sees the public tools. Listing is free and never costs gold.

```bash
curl https://pirateskills.com/api/public/agent/tools
```

## Run a public tool – no key

Reads also work as a GET with the input in the query string, handy in a browser.

```bash
curl -X POST https://pirateskills.com/api/public/agent/tools/list_events \
  -H "content-type: application/json" \
  -d '{"limit": 3}'

curl "https://pirateskills.com/api/public/agent/tools/search_knowledge?query=landing%20page&limit=2"
```

## Run a tool as yourself – with your key

Put the key in an environment variable, never in code. One gold per call.

```bash
curl -X POST https://pirateskills.com/api/public/agent/tools/my_wallet \
  -H "Authorization: Bearer $PIRATESKILLS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"limit": 5}'
```

## A tool that changes something – after the person's yes

Writes run on POST only. An agent asks the person first, every time.

```bash
curl -X POST https://pirateskills.com/api/public/agent/tools/register_for_event \
  -H "Authorization: Bearer $PIRATESKILLS_API_KEY" \
  -H "content-type: application/json" \
  -H "x-agent-client: my-script" \
  -d '{"eventId": "2026_09_23_ai_compass"}'
```

## What comes back

Always JSON with `ok`. The listing also says who you are and, per tool, `confirm` (it changes something) and its `inputSchema` as JSON Schema.

```json
{ "ok": true, "tool": "list_events", "result": [ … ] }
{ "ok": false, "error": "Sign in to use my_wallet." }
```

## Retrying safely

A tool that changes something accepts an `Idempotency-Key` header. Send the same key on a retry and you get the first answer back (`Idempotent-Replayed: true`) instead of a second booking. Keys are kept 24 hours.

```bash
curl -X POST https://pirateskills.com/api/public/agent/tools/register_for_event \
  -H "Authorization: Bearer $PIRATESKILLS_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"eventId": "2026_09_23_ai_compass"}'
```

## OpenAPI

Every endpoint, with its input, is in the [OpenAPI description](https://pirateskills.com/openapi.json).

---
Source: https://pirateskills.com/docs/http · All docs: https://pirateskills.com/docs.md · Short overview: https://pirateskills.com/llms.txt