REST API

Everything you do in the dashboard, over HTTP and JSON. The API and the MCP server share the same registry of 84 operations and the same keys. Available on Starter and Pro.

Authentication

Create a key in Settings → API. It's shown only once: store it in your secrets manager. Send it on every request in the Authorization: Bearer pk_live_… header.

Base URL: https://jotly.si/api/v1

curl "https://jotly.si/api/v1/requests?statuses=planned,in_progress&sort=top&limit=10" \  -H "Authorization: Bearer pk_live_YOUR_KEY"

Each key has full access to its workspace. Create one per integration or agent so you can revoke it without affecting the others.

Create and respond

Path parameters go in the URL; for GET and DELETE everything else goes in the query string, and for POST, PATCH and PUT in a JSON body. Every resource comes wrapped in its name ({ request }, { board }, { member }). Creating returns 201; relationships (vote, subscribe, tag) return { ok: true } and deletes return 204 with no body.

curl -X POST "https://jotly.si/api/v1/requests" \  -H "Authorization: Bearer pk_live_YOUR_KEY" \  -H "Content-Type: application/json" \  -d '{    "board_id": "brd_123",    "title": "Automatic monthly export",    "body": "Send invoices to the accountant automatically.",    "author": { "external_id": "u_812" }  }'

HTTP/1.1 201 CreatedX-Request-Id: req_8f2k1x0c9q7m3v5b6n4z {  "request": {    "id": "post_4j8w2q",    "number": 42,    "title": "Automatic monthly export",    "status": "pending",    "board": { "id": "brd_123", "name": "Features", "type": "public" },    "author": { "id": "cus_9x1", "external_id": "u_812", "type": "user", "first_name": "Lucía" },    "tags": [],    "attachments": [],    "vote_count": 1,    "comment_count": 0  }}

Members (author, voter, subscriber, actor, member) are referenced with { id } or { external_id } (your user id). Jotly also accepts { email }; with external_id or email, the member is created if it doesn't exist. The actor of a reply or a status change must be on your team; without one, whoever created the key acts.

Pagination

Every list returns { <resource>: [...], next_cursor }. Request the next page with cursor set to the previous page's next_cursor; when it's null, there are no more. limit ranges from 1 to 100 (10 for requests and changelog, 20 for conversations and members, 50 for votes and the timeline). The cursor is opaque: don't build it by hand.

Idempotency

POST /requests, POST /changelogs, POST /assets/import, and conversation replies and notes accept the Idempotency-Key header. For 24 hours, repeating the request with the same key and the same body returns the original response (with the Idempotent-Replayed: true header) instead of creating it again.

curl -X POST "https://jotly.si/api/v1/conversations/cnv_123/replies" \  -H "Authorization: Bearer pk_live_YOUR_KEY" \  -H "Idempotency-Key: run-2026-10-19-cnv_123" \  -H "Content-Type: application/json" \  -d '{ "body": "Done, all fixed now.", "actor": { "external_id": "support-agent" } }'

Rate limits

Each key has a per-minute limit shared by the REST API and the MCP server (120 by default). Past it, the response is 429 with the Retry-After header and the wait in seconds in details.retry_after_seconds.

HTTP/1.1 429 Too Many RequestsRetry-After: 23 {  "error": {    "code": "rate_limited",    "message": "Too many requests: the limit is 120 per minute per key",    "details": { "retry_after_seconds": 23 }  }}

Errors

Errors respond with the matching HTTP status and { error: { code, message, details? } }. Every response, errors included, carries the X-Request-Id header: include it if you contact support.

{  "error": {    "code": "invalid_api_token",    "message": "Invalid API token"  }}

Members and companies

POST /members/sync creates or updates a member by external_id; their traits are merged (a trait set to null is removed) and companies creates or updates their companies and links the member to them. The widget's identify accepts the same companies. DELETE /members/:member_id erases their personal data and keeps their requests, comments and votes; after that, reading or deleting the member again returns 410 member_erased.

Attachments and files: Jotly doesn't have file storage yet, so attachment_urls, addRequestAttachments, addCommentAttachments, POST /assets and POST /assets/import respond 422 invalid_attachment or invalid_asset. Listing and removing attachments does work.

Operations

Every parameter is detailed in the OpenAPI spec. You can import it into Postman or Insomnia, or generate a client from it.

Boards

Requests

Files

Changelog

Members

Companies

Conversations