API reference / Collectors

Assistant

7 operations.

GET/api/v1/assistant

Whether the assistant can answer

Signed inBeta: may change

Whether the assistant is configured on this deployment, and the caller’s plan (which sets how much it may answer).

SDK: collector.getAssistantStatus()
Key scopes: assistant:use(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Responses

200Its status and the collector’s plan.
object
- configuredbooleanrequired
  The assistant can answer on this deployment.
- planenumrequired
  One offreecollectorpro
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/assistant' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getAssistantStatus();

POST/api/v1/assistant

Send a message

Signed inBeta: may change

Send the newest message only (a new user message, or the last assistant message carrying approval decisions); the history lives on the server. Answers an AI SDK 7 UI message stream (text/event-stream). Errors before streaming are problem+json.

SDK: collector.chatWithAssistant()
Key scopes: assistant:use(API keys are coming soon)
Headers: X-Request-Id

Request body (required, application/json)

object

threadIdstring (uuid)required
messageobjectrequired
Fields of message
- idstringrequired
- roleenumrequired
  One ofuserassistant
- partsarray of anyrequiredat most 400 items
triggerenumoptional
One ofsubmit-messageregenerate-message

Responses

200A UI message stream (text/event-stream).

Errors (400, 401, 402, 409, 429, 500, 503)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
402ai_budget_exhausted
ai_budget_exhausted: The plan’s AI budget for the month is used up.
409thread_out_of_date change_already_made
thread_out_of_date: The conversation changed elsewhere; reload it.
change_already_made: That proposed change was already approved.
429turn_in_progress rate_limited
turn_in_progress: One turn per collector at a time.
rate_limited: Too many messages; slow down.
500internal
internal: Something went wrong on our side (quote the requestId).
503assistant_not_configured
assistant_not_configured: The assistant isn’t set up here.

curl

curl -X POST 'https://collection.id/api/v1/assistant' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.chatWithAssistant({ body: { … } });

POST/api/v1/assistant/preview

Preview a proposed change

Signed inBeta: may change

Exactly what an approval card’s change would do, from live data, by the same code that runs it after approval. Read-only; uses no AI.

SDK: collector.previewAssistantChange()
Key scopes: assistant:use(API keys are coming soon)
Headers: X-Request-Id

Request body (required, application/json)

object

toolstringrequired
addToCollection, addToWishlist, updateItems or requestHold.
inputanyrequired
The tool call’s input, as the assistant proposed it.

Responses

200The preview.
object
- previewAssistantWritePreviewrequired

Errors (400, 401, 429, 500)

400invalid_request invalid_json invalid_tool
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_tool: Only proposed changes have previews.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
429rate_limited
rate_limited: Too many previews at once.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/assistant/preview' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.previewAssistantChange({ body: { … } });

GET/api/v1/assistant/threads

Your conversations

Signed inBeta: may change

Newest activity first. Page with ?before=<nextCursor>.

SDK: collector.listAssistantThreads()
Key scopes: assistant:use(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`limit`optional	query	integer	1–100 · default 50
`before`optional	query	string (date-time)	The previous page’s nextCursor.

Responses

200A page of conversations.
object
- threadsarray of AssistantThreadrequired
  Newest activity first.
- nextCursorstring (date-time) or nullrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 401, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/assistant/threads' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listAssistantThreads({ query: { … } });

GET/api/v1/assistant/threads/{id}

A conversation

Signed inBeta: may change

The conversation with its newest messages, oldest first.

SDK: collector.getAssistantThread()
Key scopes: assistant:use(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Responses

200The conversation.
AssistantThreadDetail
A conversation with its messages.
- threadAssistantThreadrequired
- messagesarray of objectrequired
  The newest messages, oldest first.
  Fields of messages
  idstringrequired
  roleenumrequired
  One ofsystemuserassistant
  metadataanyoptional
  { createdAt }: when the server created the message.
  partsarray of anyrequired
- hasEarlierbooleanoptional
  Older messages exist that weren’t loaded.
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found thread_not_found
not_found: Nothing at that address.
thread_not_found: No such conversation of yours.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/assistant/threads/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getAssistantThread({ path: { id } });

DELETE/api/v1/assistant/threads/{id}

Delete a conversation

Signed inBeta: may change

Its messages go with it.

SDK: collector.deleteAssistantThread()
Key scopes: assistant:use(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Responses

200Deleted.
object
- ok"true"required

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X DELETE 'https://collection.id/api/v1/assistant/threads/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.deleteAssistantThread({ path: { id } });

PATCH/api/v1/assistant/threads/{id}

Rename or pin a conversation

Signed inBeta: may change

Change a conversation’s title, its pin, or both. Send at least one.

SDK: collector.updateAssistantThread()
Key scopes: assistant:use(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Request body (required, application/json)

object

titlestringoptional1–200 characters
pinnedbooleanoptional

Responses

200The conversation.
object
- threadAssistantThreadrequired

Errors (400, 401, 404, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found thread_not_found
not_found: Nothing at that address.
thread_not_found: No such conversation of yours.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X PATCH 'https://collection.id/api/v1/assistant/threads/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.updateAssistantThread({ path: { id }, body: { … } });