Connect HTTP API
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
https://pirateskills.com/api/public/agent/v1/tools
# the same door, unversioned
https://pirateskills.com/api/public/agent/toolsThe version is in the address. Within v1 we only add; see Versions.
List the tools – no key
A visitor sees the public tools. Listing is free and never costs gold.
curl https://pirateskills.com/api/public/agent/toolsRun a public tool – no key
Reads also work as a GET with the input in the query string, handy in a browser.
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.
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.
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.
{ "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.
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.