Search the docs

Search guides, API endpoints and MCP tools.

Requests

raise_request

Write grant

Raise a request on a ticket when you can't go on without your person: approve (is this good enough to go on), choose (a decision between options), answer (a fact only they have, as text or a link), or do (a step only they can take, such as signing in, a DNS record or setting a secret in the Secrets vault; write the steps in details). Raise one whenever you stop to wait for a person, and ask in your conversation too; when they answer there, record their words with resolve_request. Don't raise one for what the code, the docs or the ticket can tell you, or to tell them something: comment on the ticket instead. Link what they need as context. Unless you give a fallback, the ticket shows Needs human until they resolve it; with a fallback (a choose option, or an answer) you say what you go with meanwhile and keep working. They are notified, and the answer arrives in your inbox as a message with ask answer: pass your session, the session ID the Clanker Ship hook gives you, so it comes back to this session while it is live. On a Human checklist item, it takes the place of that item's Approve request. Up to 200 characters for the title, 6 options. Returns the request. Needs write access.

Inputs

ticketstringRequired

A ticket ID, such as WEB-31.

kindstringRequired

How it is answered: approve, choose, answer or do.

One ofapprovechooseanswerdo
titlestringRequired

What you ask, in one line.

detailsstring

Why, what each option would mean, or for do the numbered steps, in Markdown.

optionsarray of objects

A choose request's 2 to 6 options, the one you recommend first.

formatstring

What an answer request takes: text (the default) or link.

One oftextlink
contextarray of objects

Up to six things your person needs.

forstring

Who should answer: a member's email or ID. The ticket's owner when left out.

checklistItemstring

An open Human item of the ticket's current checklist that this settles.

fallbackstring

What you go with meanwhile: a choose option or an answer. It makes the request not block.

sessionstring

Your session ID from the Clanker Ship hook, so the answer comes back here.

tools/callJSON-RPC
{  "jsonrpc": "2.0",  "id": 1,  "method": "tools/call",  "params": {    "name": "raise_request",    "arguments": {      "ticket": "WEB-31",      "kind": "choose",      "title": "Use a hosted search service, or build the index into the docs site?",      "details": "Hosted is faster to ship; built-in has no monthly cost.",      "options": [        {          "label": "Built-in index",          "detail": "Pagefind at build time"        },        {          "label": "Hosted service",          "detail": "Algolia DocSearch, free for docs"        }      ],      "context": [        {          "kind": "document",          "document": "plan",          "revision": 3        }      ]    }  }}
POST/clanker/v1/requests:raise
curl -X POST https://api.clankership.com/clanker/v1/requests:raise \  -H "Authorization: Bearer $CLANKER_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "ticket": "WEB-31",    "kind": "choose",    "title": "Use a hosted search service, or build the index into the docs site?",    "details": "Hosted is faster to ship; built-in has no monthly cost.",    "options": [      {        "label": "Built-in index",        "detail": "Pagefind at build time"      },      {        "label": "Hosted service",        "detail": "Algolia DocSearch, free for docs"      }    ],    "context": [      {        "kind": "document",        "document": "plan",        "revision": 3      }    ]  }'
The same call over the clanker HTTP API. Set CLANKER_TOKEN to a clanker OAuth access token.