API Endpoints

OpenSync exposes a REST API through Convex HTTP endpoints. The session, sync and search endpoints use API keys; /health is public.

Base URL

For the hosted version:

https://api.opensync.dev

For your own deployment, use its HTTP actions URL (.convex.site) or a verified custom HTTP domain. Do not use the Convex client domain for REST requests:

https://your-deployment.convex.site

Authentication

All endpoints (except /health) require an API key in the Authorization header:

Authorization: Bearer osk_your_api_key_here

Generate API keys from the Settings page in the dashboard. Keys start with osk_ and are tied to your user account.

API keys provide full access to your account data. Do not commit them to version control or share them publicly.

Sync endpoints

These endpoints are used by sync plugins to push session and message data.

POST /sync/session

Create or update a session. Uses upsert logic based on externalId, so calling this multiple times with the same externalId is safe. Request body:

{
  "externalId": "unique-session-id-from-your-tool",
  "source": "opencode",
  "title": "Fix the login redirect bug",
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "projectPath": "/Users/me/projects/my-app",
  "projectName": "my-app",
  "promptTokens": 3200,
  "completionTokens": 1800,
  "cost": 0.037,
  "durationMs": 45000
}

Required fields:

Field	Type	Description
`externalId`	string	Unique session ID from the originating tool. Used for dedup.

Optional fields:

Field	Type	Description
`title`	string	Session title
`model`	string	Model name
`provider`	string	Model provider
`projectPath`	string	Absolute project path
`projectName`	string	Project directory name
`durationMs`	number	Session duration in ms
`source`	string	Plugin identifier, such as `opencode` or `claude-code`
`promptTokens`	number	Cumulative input tokens for the session
`completionTokens`	number	Cumulative output tokens for the session
`cost`	number	Estimated USD cost
`createdAt`	number	Original timestamp in milliseconds; single-session endpoint only

Response:

{
  "ok": true,
  "sessionId": "j57a..."
}

POST /sync/message

Create or update a message within a session. The session is identified by sessionExternalId and will be auto-created if it does not exist. Request body:

{
  "sessionExternalId": "unique-session-id-from-your-tool",
  "externalId": "unique-message-id",
  "role": "assistant",
  "parts": [
    {
      "type": "text",
      "content": "Here's how to fix the redirect issue..."
    },
    {
      "type": "tool-call",
      "content": { "toolName": "edit_file", "path": "src/auth.ts" }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "promptTokens": 0,
  "completionTokens": 450,
  "durationMs": 3200
}

Required fields:

Field	Type	Description
`sessionExternalId`	string	The `externalId` of the parent session
`externalId`	string	Unique message ID for dedup
`role`	string	One of: “user”, “assistant”, “system”, “tool”, “unknown”

Optional fields:

Field	Type	Description
`parts`	array	Objects with `type` and `content`; send a complete parts snapshot when updating a message
`textContent`	string	Plain text of the message
`source`	string	Source for an automatically created session
`createdAt`	number	Original timestamp in milliseconds; single-message endpoint only
`model`	string	Model used for this message
`promptTokens`	number	Input tokens for this message
`completionTokens`	number	Output tokens for this message
`durationMs`	number	Time to generate the response

Part types:

Type	Fields	Description
`text`	`content`	Plain text content
`tool-call`	`content`	Tool-call details inside the content value
`tool-result`	`content`	Result returned by a tool

POST /sync/batch

Sync multiple sessions and messages in a single request. Preferred for bulk operations to reduce write conflicts. Request body:

{
  "sessions": [
    { "externalId": "s1", "source": "opencode", "promptTokens": 100, "completionTokens": 50, "cost": 0.001 }
  ],
  "messages": [
    { "sessionExternalId": "s1", "externalId": "m1", "role": "user", "parts": [{"type": "text", "content": "Hello"}] }
  ]
}

Response:

{
  "ok": true,
  "sessions": 1,
  "messages": 1,
  "errors": []
}

The batch response counts inserted and updated items; unchanged retries are excluded. Inspect errors even when the HTTP status is 200 and ok is true. The current batch validators do not accept createdAt timestamps. Timestamp compatibility is tracked in issue #29.

GET /sync/sessions/list

Returns { "sessionIds": [...] } containing the authenticated user’s external session IDs. Plugins use this to skip already imported sessions.

Query endpoints

GET /api/sessions

Returns { "sessions": [...] }, ordered by most recently updated. limit defaults to 50. This route currently has no cursor or source-filter parameter. Each session includes id, externalId, token totals, cost, visibility, message count and timestamps. Title, model, provider and project fields are present when recorded. Use id for the read and export endpoints below, not the plugin’s external ID.

GET /api/sessions/get

Pass the required id query parameter. Returns { "session": {...}, "messages": [...] } for a session owned by the authenticated user. Messages include their parts.

curl --get "https://api.opensync.dev/api/sessions/get" \
  -H "Authorization: Bearer $OPENSYNC_API_KEY" \
  --data-urlencode "id=$SESSION_ID"

Search endpoint

GET /api/search

Parameter	Default	Description
`q`	Required	Search query
`type`	`fulltext`	`fulltext`, `semantic` or `hybrid`
`limit`	20	Maximum results

curl --get "https://api.opensync.dev/api/search" \
  -H "Authorization: Bearer $OPENSYNC_API_KEY" \
  --data-urlencode "q=authentication middleware" \
  --data-urlencode "type=fulltext" \
  --data-urlencode "limit=10"

Returns { "results": [...] } with session metadata. Full-text results use id; semantic results use _id; hybrid can include either shape. Read the ID with result.id ?? result._id. Scores, snippets and matchedIn are not returned by this REST API. Semantic and hybrid requests require configured embeddings and a working OpenAI API key.

Context endpoint

GET /api/context

Parameter	Default	Description
`q`	Required	Natural-language query
`limit`	5	Maximum sessions
`format`	`text`	`text` or `messages`

Uses semantic search. Text format returns { "text": "...", "sessionCount": 1 }. Messages format returns { "messages": [...], "sessionCount": 1 }; each message contains role, content and session metadata.

Export endpoint

GET /api/export

Exports one owned session. Pass its required id and optional format:

Format	Response
`json` (default)	JSON object with session metadata and role/content messages
`markdown`	Markdown attachment
`jsonl`	JSON object with `content` and `filename`; write the content to a file yourself

Evaluation dataset export is a separate route, /api/export/evals; it is not selected with /api/export?format=deepeval. Use the dashboard export workflow for evaluation exports while API-key access to that separate route is being verified.

Statistics endpoint

GET /api/stats

Returns sessionCount, messageCount, totalTokens, totalCost, totalDurationMs and modelUsage. Each model entry includes tokens, cost and sessions. These values depend on data supplied by your plugins.

Health endpoint

GET /health

Public endpoint. Returns status: "ok" and timestamp in milliseconds.

Errors and retries

API errors use { "error": "message" }. See Error handling. No fixed per-minute API quota is documented by the current implementation. Use bounded requests and exponential backoff for temporary failures; honor Retry-After if an upstream service supplies it.

Getting Started

Dashboard

Plugins

API Reference

Search

Authentication

Hosting & Deploy

Fork & Self-Host

Troubleshooting

API Endpoints

API Endpoints

Base URL

Authentication

Sync endpoints

POST /sync/session

POST /sync/message

POST /sync/batch

GET /sync/sessions/list

Query endpoints

GET /api/sessions

GET /api/sessions/get

Search endpoint

GET /api/search

Context endpoint

GET /api/context

Export endpoint

GET /api/export

Statistics endpoint

GET /api/stats

Health endpoint

GET /health

Errors and retries

​API Endpoints

​Base URL

​Authentication

​Sync endpoints

​POST /sync/session

​POST /sync/message

​POST /sync/batch

​GET /sync/sessions/list

​Query endpoints

​GET /api/sessions

​GET /api/sessions/get

​Search endpoint

​GET /api/search

​Context endpoint

​GET /api/context

​Export endpoint

​GET /api/export

​Statistics endpoint

​GET /api/stats

​Health endpoint

​GET /health

​Errors and retries

API Endpoints

Base URL

Authentication

Sync endpoints

POST /sync/session

POST /sync/message

POST /sync/batch

GET /sync/sessions/list

Query endpoints

GET /api/sessions

GET /api/sessions/get

Search endpoint

GET /api/search

Context endpoint

GET /api/context

Export endpoint

GET /api/export

Statistics endpoint

GET /api/stats

Health endpoint

GET /health

Errors and retries