API reference / Collectors
6 operations.
/api/v1/questionsThe caller’s questions about listed books, latest activity first.
collector.listMyQuestions()questions:read(API keys are coming soon)If-None-MatchX-Request-Idobject
unauthorized: Not signed in (no session or token, or an expired one).
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/questions' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listMyQuestions();/api/v1/questionsAsk about a listed book. An open question about the same book takes the message instead; the store’s staff are told.
collector.askQuestion()questions:write(API keys are coming soon)Idempotency-KeyX-Request-Idobject
listingIdstring (uuid)requiredbodystringrequired1–2000 charactersobject
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
unauthorized: Not signed in (no session or token, or an expired one).
idempotency_in_progress: The first request with this key is still running.
listing_unavailable: The book isn’t listed, or not enough copies are left.
store_unavailable: The store isn’t taking requests right now.
store_closed: The store has closed.
own_store: The book is in the caller’s own store.
idempotency_key_reused: This key was used for a different request.
rate_limited: Too many requests; wait the Retry-After seconds.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/questions' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.askQuestion({ body: { … } });/api/v1/questions/{questionId}/closeThe collector or the store closes it; its history stays readable.
collector.closeQuestion()questions:writestore:questions:write(API keys are coming soon)X-Request-Id| Name | In | Type | About |
|---|---|---|---|
questionIdrequired | path | string (uuid) |
object
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/questions/<questionId>/close' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.closeQuestion({ path: { questionId } });/api/v1/questions/{questionId}/holdStore staff answer a question by holding the book: an accepted hold for the store’s hold days. The question closes and links to the hold; the collector is told.
collector.holdFromQuestion()store:questions:writestore:holds:write(API keys are coming soon)Idempotency-KeyX-Request-Id| Name | In | Type | About |
|---|---|---|---|
questionIdrequired | path | string (uuid) |
object
quantityintegeroptional1–50 · default 1object
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
unauthorized: Not signed in (no session or token, or an expired one).
forbidden: The caller’s side can’t do this (only the store answers a request…).
not_found: Nothing at that address.
idempotency_in_progress: The first request with this key is still running.
question_closed: The question is closed.
already_held: The book is already held for this collector.
listing_unavailable: The book isn’t listed, or not enough copies are left.
store_unavailable: The store isn’t taking requests right now.
store_closed: The store has closed.
idempotency_key_reused: This key was used for a different request.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/questions/<questionId>/hold' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.holdFromQuestion({ path: { questionId }, body: { … } });/api/v1/questions/{questionId}/messagesThe thread between the collector who asked and the store’s staff, oldest first.
collector.listQuestionMessages()questions:readstore:questions:read(API keys are coming soon)If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
questionIdrequired | path | string (uuid) |
object
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/questions/<questionId>/messages' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listQuestionMessages({ path: { questionId } });/api/v1/questions/{questionId}/messagesOpen threads only. The other side gets one notification per unread thread.
collector.postQuestionMessage()questions:writestore:questions:write(API keys are coming soon)Idempotency-KeyX-Request-Id| Name | In | Type | About |
|---|---|---|---|
questionIdrequired | path | string (uuid) |
object
bodystringrequired1–2000 charactersobject
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
idempotency_in_progress: The first request with this key is still running.
question_closed: The question is closed.
idempotency_key_reused: This key was used for a different request.
rate_limited: Too many requests; wait the Retry-After seconds.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/questions/<questionId>/messages' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.postQuestionMessage({ path: { questionId }, body: { … } });