REST API requests and responses

JSON REST results use:

{"success":true,"data":{"status":"accepted"},"requestId":"REQUEST_UUID"}

Failures use:

{"success":false,"error":{"code":"CONFLICT","message":"Read the current version before trying again."},"requestId":"REQUEST_UUID"}

The objects are illustrative shapes, not universal payloads or fixed error wording. Save request IDs for support; exclude credentials and private content from diagnostic logs.

Send Content-Type: application/json. Delegated keyed REST mutation routes require Idempotency-Key; MCP places the same key in idempotencyKey. If both REST body and header contain a key, they must match. Path IDs and any repeated body IDs must agree.

POST /api/v1/tasks HTTP/1.1
Host: api.artie.ai
Authorization: Bearer <OAUTH_ACCESS_TOKEN>
Content-Type: application/json
Idempotency-Key: project-summary-001

{"artisanId":"ARTISAN_UUID","instructions":"Summarize the selected project notes with sources.","timeZone":"UTC","inputRefs":[]}

Creation and messages normally return HTTP 202 for accepted work. Staged uploads return 201. Most reads and applied controls return 200. A 200 setup-required result is a setup instruction, not a completed business operation. Read-only POST routes /search, /context/read and /images/read do not require mutation keys.

Task answers and full refinements require an explicit expectedRevision from the task read. Task controls can fetch the current revision when omitted. task refine --append first reads the complete current brief and revision. An explicit revision makes the intended edit clear. Never force a stale mutation by deleting its revision check.

Keys for delegated operations are normally 8–128 characters. Keep the same operation, payload and key when recovering a lost response. Reusing a key for a different payload conflicts. A deliberate new operation needs its own key after the old operation has been reconciled.

JSON request bodies are capped at 1 MiB. REST booleans must be literal true/false, numeric query values must be nonnegative integer strings, and repeated status values are supported. Do not repeat other scalar query fields.