# API quickstart

> Schedule a post with curl in three requests.

You need an [API key](https://orbitwrite.com/docs/developers/authentication) and at least one connected channel.

### 1. Find a channel

```bash
curl https://orbitwrite.com/api/v1/connected-accounts \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
```

Note the `id` of the channel you want to post to.

### 2. Pick a time

Ask for the next free posting slot on that channel:

```bash
curl "https://orbitwrite.com/api/v1/scheduling/suggestions?accountIds=acc_123&strategy=first-available" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
```

Or use any ISO 8601 instant you like.

### 3. Create the post

```bash
curl https://orbitwrite.com/api/v1/posts \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2026-10-01T09:00:00Z",
    "accounts": [
      {
        "accountId": "acc_123",
        "isSynced": true,
        "items": [{ "id": "1", "content": "Hello from the Orbitwrite API" }]
      }
    ]
  }'
```

The response carries the post's `groupIds`. To publish straight away instead, add `"publishNow": true`; `scheduledAt`
is still required, so send the current time.

## Check it published

A publish-now returns as soon as the post is accepted, before the network has answered. Read the outcome per channel:

```bash
curl "https://orbitwrite.com/api/v1/posts/publish-status?groups=grp_123" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
```

## Add an image

1. Ask for an upload URL, declaring the file's exact type and size:
   ```bash
   curl https://orbitwrite.com/api/v1/media/create-upload-url \
     -H "Authorization: Bearer $ORBITWRITE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "photo.jpg", "mime_type": "image/jpeg", "size_bytes": 123456}'
   ```
2. `PUT` the bytes to the `upload_url` it returns, with the same `Content-Type`:
   ```bash
   curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @photo.jpg
   ```
3. Confirm it arrived, then attach it by id:
   ```bash
   curl https://orbitwrite.com/api/v1/media/confirm \
     -H "Authorization: Bearer $ORBITWRITE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"media_ids": ["med_123"]}'
   ```
   In the post, add `"mediaIds": ["med_123"]` to an item.

Videos use `POST /media/create-stream-upload` instead, which returns a resumable [TUS](https://tus.io) upload so a
large file survives a flaky connection.

## Next

- The [SDK](https://orbitwrite.com/docs/developers/sdk) wraps all of this, including per-channel copy and threads.
- Every endpoint is in the [API reference](https://orbitwrite.com/docs/api-reference).