# DoroSocial Public API Quickstart

Status: Initial implementation reference  
Created: 2026-07-04

This document describes how to use API tokens with trusted apps, AI tools, scripts, and customer integrations.

Stable downloadable docs:

- OpenAPI YAML: `/developers/openapi.yaml`
- Quickstart Markdown: `/developers/quickstart.md`

## Create an API Token

1. Open `Settings > API tokens`.
2. Use the `Connect an app or AI tool` access level for tools that need to create content, upload media, create or schedule posts, and read post status.
3. Choose an expiration. The default is 90 days. The maximum is 1 year.
4. Copy the token immediately. DoroSocial shows the raw token only once.

API tokens are available to paid, email-verified users. Free users can view the page but cannot create tokens. Each user can have up to 10 active API tokens. Revoked and expired tokens do not count toward the limit.

## Authentication

Pass the token as a bearer token:

```bash
curl http://localhost:8000/api/v1/public/context \
  -H "Authorization: Bearer doro_test_ab12cd34_xxx"
```

Never put API tokens in source code, screenshots, logs, or public prompts. Revoke leaked tokens from `Settings > API tokens`.

## Brand Context

Most API operations need a brand.

If an account has one active brand, DoroSocial defaults to it. If an account has multiple active brands, include `brand_id`.

List brand context:

```bash
curl http://localhost:8000/api/v1/public/context \
  -H "Authorization: Bearer $DORO_API_TOKEN"
```

List brands:

```bash
curl http://localhost:8000/api/v1/public/brands \
  -H "Authorization: Bearer $DORO_API_TOKEN"
```

If multiple brands exist and `brand_id` is omitted, the API returns:

```json
{
  "detail": {
    "code": "brand_required",
    "message": "This account has multiple active brands. Include brand_id in the request.",
    "brands": [{ "id": 1, "name": "Main Brand" }]
  }
}
```

## Scopes

Initial scopes:

- `brand:read` - read account and brand context
- `content:create` - create source content items
- `media:upload` - upload media through multipart upload routes
- `posts:create` - create platform post drafts
- `posts:schedule` - schedule posts
- `posts:read` - read post and publishing status

Public API terminology uses `posts`. Internally, these map to DoroSocial deployment rows.

## Create Content

```bash
curl http://localhost:8000/api/v1/public/content \
  -H "Authorization: Bearer $DORO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": 1,
    "title": "Repurpose webinar into clips",
    "content_type": "TEXT",
    "status": "DRAFT",
    "description": "Source notes for the agent"
  }'
```

## Create or Schedule a Post

Create a draft post:

```bash
curl http://localhost:8000/api/v1/public/posts \
  -H "Authorization: Bearer $DORO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": 1,
    "content_id": 456,
    "platform": "LI",
    "text": "Post copy"
  }'
```

Schedule a post:

```bash
curl http://localhost:8000/api/v1/public/posts \
  -H "Authorization: Bearer $DORO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": 1,
    "content_id": 456,
    "platform": "LI",
    "text": "Scheduled post copy",
    "scheduled_for": "2026-07-10T16:00:00Z"
  }'
```

Scheduling requires both `posts:create` and `posts:schedule`.

## Read Post Status

```bash
curl "http://localhost:8000/api/v1/public/posts/789/status?brand_id=1" \
  -H "Authorization: Bearer $DORO_API_TOKEN"
```

## Multipart Media Upload

The public API exposes wrappers around the same multipart upload flow the app uses:

- `POST /api/v1/public/media/uploads/multipart/start`
- `POST /api/v1/public/media/uploads/multipart/sign-parts`
- `POST /api/v1/public/media/uploads/multipart/complete`

The routes enforce the same brand ownership, object-key ownership, upload-size, storage-quota, and content validation rules as the browser app.

Completing an upload creates or replaces content and requires both `media:upload` and `content:create`.