Developers

Public API

Build your own dashboard, exports, and automations on top of your diary data.

Start with Advanced

Requirements

• Plan: Advanced plan is required for Public API access.
• API key: Create and revoke keys from app settings (Settings > API Keys).
• Base URL: https://api.deariary.com/api/v1

Authentication

All requests must include Authorization: Bearer deariary_sk_... . Keys are scoped, and requests without required scope return 403.

Authorization: Bearer deariary_sk_...

Available scopes

Rate limits and headers

• 120 requests per minute per API key.
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After
• Response header: X-Request-Id
• CORS: Access-Control-Allow-Origin: *

Error format

Errors are returned as application/problem+json. Public API auth/rate-limit errors and validation errors are normalized into Problem Details responses. application/problem+json

Error response example

{
  "type": "https://developer.deariary.com/errors/missing-api-key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "MISSING_API_KEY"
}

Error response example

{
  "type": "https://developer.deariary.com/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit of 120 requests per minute exceeded. Retry after 24 seconds."
}

Common errors

Endpoints

GET /api/v1/entries

Returns a paginated list of entries. Required scope: entries:list

Query parameters

Response fields

Sample request

curl -H "Authorization: Bearer deariary_sk_xxx" \
  "https://api.deariary.com/api/v1/entries?from=2026-02-01&to=2026-02-28&tag=deep-work&limit=2&offset=0"

Success response example

{
  "data": [
    {
      "date": "2026-02-24",
      "title": "A productive Monday",
      "content": "# A productive Monday\n\nToday I worked on...",
      "tags": ["coding", "deep-work"],
      "generatedAt": "2026-02-25T03:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

GET /api/v1/entries/:date

Returns one entry by date. Required scope: entries:read

Response fields

Sample request

curl -H "Authorization: Bearer deariary_sk_xxx" \
  "https://api.deariary.com/api/v1/entries/2026-02-24"

Success response example

{
  "date": "2026-02-24",
  "title": "A productive Monday",
  "content": "# A productive Monday\n\nToday I worked on...",
  "tags": ["coding", "deep-work"],
  "sources": ["github", "calendar", "slack"],
  "generatedAt": "2026-02-25T03:00:00.000Z",
  "wordCount": 438
}

Error response example

{
  "type": "https://developer.deariary.com/errors/entry-not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "ENTRY_NOT_FOUND"
}

GET /api/v1/tags

Returns tags with usage counts. Required scope: tags:read

Response fields

Sample request

curl -H "Authorization: Bearer deariary_sk_xxx" \
  "https://api.deariary.com/api/v1/tags"

Success response example

{
  "data": [
    {
      "slug": "deep-work",
      "displayName": "Deep Work",
      "entryCount": 18
    },
    {
      "slug": "running",
      "displayName": "Running",
      "entryCount": 9
    }
  ]
}

Incoming webhook

Advanced plan supports incoming webhook ingestion. You can send custom payloads from your own tools (Zapier, IFTTT, scripts, shortcuts), and deariary interprets them with LLM context in the next diary generation.

• Endpoint: POST /webhooks/ingest
• Auth: Authorization header with Bearer whk_...
• Payload size: up to 100KB per request
• Any JSON object or array is accepted (no fixed schema)
• Examples: mood logs, reading history, workout records, custom events
• Webhook tokens are managed in Integrations > Webhook > Settings

Sample request

curl -X POST "https://api.deariary.com/webhooks/ingest" \
  -H "Authorization: Bearer whk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-02-24T09:30:00Z",
    "source": "mood-tracker",
    "payload": {
      "mood": "great",
      "score": 8,
      "note": "Focused 3h block"
    }
  }'

Success response example

{
  "received": true
}

Error response example

{
  "type": "https://developer.deariary.com/errors/invalid-webhook-token",
  "title": "Unauthorized",
  "status": 401,
  "detail": "INVALID_WEBHOOK_TOKEN"
}