API

Authentication

All API requests require an API key sent as a Bearer token in the Authorization header.

Generate a key in Settings → API Keys. Copy the key immediately. It won't be shown again.

curl https://keen-sturgeon-487.convex.site/api/v1/trips \
  -H "Authorization: Bearer osk_your_key_here"

Scopes

The four base scopes are trips:read, trips:write, messages:read, and messages:write. Each can be limited to a single trip by appending :<tripId>. For example, a key with only the scope trips:write:jx7abc... can create and update content on that one trip but nothing else. In the settings UI, leave "Limit to trip" blank for a key that works everywhere, or paste a trip ID to scope it down.

SDKs

You do not need a client to use the REST API, but the official TypeScript SDK takes care of the tedious bits: auto-generated idempotency keys, retry with exponential backoff on 429 and 5xx, cursor pagination iterators, typed errors, and an unauthenticated share-token consumer.

TypeScript

npm install @osoto/api-client

import { OsotoClient } from '@osoto/api-client';

const client = new OsotoClient({
  apiKey: process.env.OSOTO_API_KEY!,
  baseUrl: 'https://keen-sturgeon-487.convex.site/api/v1',
});

const me = await client.me();
const { _id: tripId } = await client.createTrip({
  groupId: me.defaultGroupId!,
  title: 'Cotswolds',
  startDate: '2026-07-15',
  endDate: '2026-07-22',
});

// Async iterator loops every page automatically.
for await (const leg of client.iterateLegs(tripId)) {
  console.log(leg.title);
}

Model Context Protocol

Agents that speak MCP (Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw) can consume the REST API through @osoto/mcp-server without writing any client code.

npx @osoto/mcp-server

Full MCP setup instructions →

Rate limiting

API keys are limited to 60 requests per minute. Rate limit status is returned in response headers.

Idempotency and retries

Retries are safe. You have two tools for making sure a flaky network does not create duplicates: an Idempotency-Key header for individual mutations, and a clientRef field for upserting rows by a caller-supplied identifier.

Idempotency-Key header

Any POST, PATCH, or DELETE may include an Idempotency-Key header (max 255 characters). Retries with the same key replay the cached response; retries with the same key but a different body return 409 IDEMPOTENCY_CONFLICT. Cached responses expire after 24 hours.

curl -X POST https://keen-sturgeon-487.convex.site/api/v1/trips \
  -H "Authorization: Bearer osk_..." \
  -H "Idempotency-Key: create-trip-42" \
  -H "Content-Type: application/json" \
  -d '{"groupId":"...","title":"Cotswolds","startDate":"2026-07-15","endDate":"2026-07-22"}'

clientRef field

Pass a clientRef when creating legs, action items, map pins, or stays. It is unique per trip (or per leg for stays). Passing the same value on a retry diff-merges into the existing row instead of inserting a duplicate. clientRef pairs naturally with the batch upsert endpoints when importing a full itinerary.

Errors

Errors return a JSON object with a code and message.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields: title, startDate",
    "requestId": "req_0f9a8b7c-...",
    "details": [
      { "path": "title", "reason": "required" },
      { "path": "startDate", "reason": "required" }
    ]
  }
}

Every response carries an X-Request-Id header (mirrored in error.requestId for error responses). Include it when filing support issues so we can trace the request end-to-end.

Endpoints

Me

curl https://keen-sturgeon-487.convex.site/api/v1/me \
  -H "Authorization: Bearer osk_..."

Trips

curl https://keen-sturgeon-487.convex.site/api/v1/trips \
  -H "Authorization: Bearer osk_..."

curl -X POST https://keen-sturgeon-487.convex.site/api/v1/trips \
  -H "Authorization: Bearer osk_..." \
  -H "Content-Type: application/json" \
  -d '{"groupId":"...","title":"Summer in the Cotswolds","startDate":"2026-07-15","endDate":"2026-07-22"}'

curl https://keen-sturgeon-487.convex.site/api/v1/trips/TRIP_ID/export \
  -H "Authorization: Bearer osk_..."

curl -X POST "https://keen-sturgeon-487.convex.site/api/v1/trips/TRIP_ID/sync?dryRun=true" \
  -H "Authorization: Bearer osk_..." \
  -H "Content-Type: application/json" \
  -d '{"legs":[{"order":0,"title":"Tokyo","destination":"Tokyo","startDate":"2026-07-15","endDate":"2026-07-20","timezone":"Asia/Tokyo","clientRef":"leg-tok-1"}],"mapPins":[{"name":"Sensoji","lat":35.7148,"lng":139.7967,"clientRef":"pin-sensoji"}]}'

Trip legs

curl -X POST https://keen-sturgeon-487.convex.site/api/v1/trips/TRIP_ID/legs:batch \
  -H "Authorization: Bearer osk_..." \
  -H "Content-Type: application/json" \
  -d '{"items":[{"order":0,"title":"Tokyo","destination":"Tokyo","startDate":"2026-07-15","endDate":"2026-07-20","timezone":"Asia/Tokyo","clientRef":"leg-tok-1"}]}'

Action items

Commitments

Map pins

Messages

Trip members

Shared (no auth)

Generate a share token with POST /trips/{tripId}/share-token. The token grants unauthenticated read access to the safe projection of the trip. Sensitive fields like wifiPassword, doorCode, hostPhone, confirmationNumber, and check-in instructions are stripped. Revoke with DELETE /trips/{tripId}/share-token.

curl https://keen-sturgeon-487.convex.site/api/v1/shared/trips/SHARE_TOKEN