# raise_request

`tools/call` · `POST /clanker/v1/requests:raise`

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.

- Area: Requests
- Needs the write grant.

## Inputs

- `ticket` (string, required): A ticket ID, such as WEB-31.
- `kind` (string, one of: `approve`, `choose`, `answer`, `do`, required): How it is answered: approve, choose, answer or do.
- `title` (string, required): What you ask, in one line.
- `details` (string): Why, what each option would mean, or for do the numbered steps, in Markdown.
- `options` (array of objects): A choose request's 2 to 6 options, the one you recommend first.
  - `label` (string, required): The option, up to 100 characters.
  - `detail` (string): A line that explains it.
- `format` (string, one of: `text`, `link`): What an answer request takes: text (the default) or link.
- `context` (array of objects): Up to six things your person needs.
  - When `kind` is `document`
    - `kind` (string, required): A ticket document at a revision. Always `document`.
    - `document` (string, required): The document's slug, such as plan.
    - `revision` (integer, required): The revision to read, from 1. From -9,007,199,254,740,991 to 9,007,199,254,740,991.
  - When `kind` is `pull_request`
    - `kind` (string, required): A pull request. Always `pull_request`.
    - `url` (string, required): The pull request's URL.
  - When `kind` is `link`
    - `kind` (string, required): A link, such as a preview. Always `link`.
    - `label` (string, required): What the link opens, such as Preview.
    - `url` (string, required): A full http or https URL.
  - When `kind` is `command`
    - `kind` (string, required): A command to run. Always `command`.
    - `command` (string, required): The command, such as pnpm dev.
- `for` (string): Who should answer: a member's email or ID. The ticket's owner when left out.
- `checklistItem` (string): An open Human item of the ticket's current checklist that this settles.
- `fallback` (string): What you go with meanwhile: a choose option or an answer. It makes the request not block.
- `session` (string): Your session ID from the Clanker Ship hook, so the answer comes back here.

## Request

```json
{
  "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
        }
      ]
    }
  }
}
```

## HTTP request

The same call over the clanker HTTP API, with a clanker OAuth access token:

```bash
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
      }
    ]
  }'
```