API

인증

모든 API 요청에는 Authorization 헤더에 Bearer 토큰으로 API 키가 필요합니다.

설정 → API 키에서 키를 생성하세요. 키를 즉시 복사하세요. 다시 표시되지 않습니다.

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 →

속도 제한

API 키는 분당 60개 요청으로 제한됩니다. 속도 제한 상태는 응답 헤더에 반환됩니다.

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.

오류

오류는 코드와 메시지를 포함하는 JSON 객체로 반환됩니다.

{
  "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.

엔드포인트

Me

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

여행

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"}]}'

일정 구간

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"}]}'

액션 아이템

Commitments

지도 핀

메시지

여행 멤버

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