Send a copilot message

Adds a message to a copilot conversation, or starts one, and queues the reply. The reply runs as a job: poll GET /jobs/{jobId} until it ends. A turn counts as an AI use, and on the free plan also as one of 10 turns per UTC day. Attachments are uploaded in the app only; to give the copilot material, write a note or upload a note file and mention or ground on it.

Required scopes: copilot:use

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key?string

A client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.

Match^[\x21-\x7E]{1,255}$

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

requestId*string

A uuid you mint for this message. It becomes the reply's job id. Sending the same message with the same requestId again returns the same turn and is not counted twice; a different message with a used requestId is 409 idempotency_conflict.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

conversationId?string

Continue this conversation. Omit it to start a new one.

Length1 <= length

message*string

The message, 1-4000 characters after trimming.

Length1 <= length <= 4000

modelTier?string

swift, scholar (the default) or sage. sage needs a paid plan; a free user gets 400 with details.reason premium-only.

Default"scholar"

Value in

"swift"
"scholar"
"sage"

research?boolean

Let the copilot search the web for this reply.

Defaultfalse

context?

What a new conversation is about: general, a note (noteId), a subject (subjectId) or a practice test explanation (activityRef). Ignored when continuing a conversation, which keeps its own.

subjectId?string

File a new conversation under this subject. An id the user doesn't own is ignored.

Length1 <= length

retryJobId?string

Retry a failed or stopped reply: that turn's job id, sent with the same message, modelTier and research under a new requestId. The retry takes the failed turn's place in the conversation and does not count against the free plan's daily turns.

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/copilot/messages" \  -H "Content-Type: application/json" \  -d '{    "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",    "message": "string"  }'

{  "data": {    "conversationId": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a9f",    "jobId": "7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a"  }}

Send a copilot message

Authorization

Header Parameters

Request Body

Response Body

202application/json

400application/json

401application/json

402application/json

403application/json

404application/json

405application/json

409application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`