> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildpixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> REST + Socket.IO + webhooks. Trigger builds, monitor status, integrate with your own tools.

The BuildPixel API is JSON-over-HTTPS REST, with a Socket.IO channel for live build logs and outbound webhooks for event delivery.

## Base URL

```
https://api.buildpixel.io
```

## Quick example

```bash theme={null}
# 1. List your projects
curl https://api.buildpixel.io/projects \
  -H "Authorization: Bearer $TOKEN"

# 2. Trigger a build
curl -X POST \
  https://api.buildpixel.io/projects/$PROJECT_ID/build-settings/$SETTING_ID/trigger \
  -H "Authorization: Bearer $TOKEN" \
  -d '{}'

# Response: { "buildId": "65f2...", "status": "pending" }

# 3. Poll for completion (or use Socket.IO for live updates)
curl https://api.buildpixel.io/builds/$BUILD_ID \
  -H "Authorization: Bearer $TOKEN"
```

For real-time monitoring, prefer [Socket.IO](/api-reference/sockets/overview) over polling.

## Conventions

### IDs

Resource IDs are 24-char strings. URL-safe, sortable by creation time, globally unique within an org.

### Timestamps

ISO 8601, UTC:

```
2026-05-10T14:23:45.123Z
```

### Pagination

List endpoints use cursor-based pagination:

```bash theme={null}
curl "https://api.buildpixel.io/builds?limit=50&cursor=<opaque>"
```

```json theme={null}
{
  "items": [...],
  "nextCursor": "..."
}
```

`limit` defaults to 25, max 100. The cursor is opaque — don't try to parse it.

## Where to go next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    How to get a token and use it.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/api-reference/errors">
    Status codes and the error response shape.
  </Card>

  <Card title="Builds" icon="hammer" href="/api-reference/endpoints/builds">
    Trigger, list, fetch, download artifacts.
  </Card>

  <Card title="Real-time" icon="bolt" href="/api-reference/sockets/overview">
    Socket.IO for live build status and logs.
  </Card>
</CardGroup>