---
title: "API Overview"
description: "Get started with the Forkline public API."
section: "reference"
url: "https://forkline.dev/docs/reference/api-overview"
markdown: "https://forkline.dev/docs/reference/api-overview.md"
source: "src/content/docs/reference/api-overview.mdx"
---

# API Overview

The Forkline public API provides programmatic access to repositories, runners, routines, analytics, and more.

## Base URL

```
https://api.forkline.dev/v1
```

> **Info**: The API host rolls out per-environment. If `api.forkline.dev` is not yet available in your environment, contact your administrator.

## Authentication

All requests require a Personal Access Token (PAT) sent as a Bearer token:

```bash
curl -H "Authorization: Bearer fl_pat_v1_..." https://api.forkline.dev/v1/me
```

See [Authentication](https://forkline.dev/docs/reference/authentication) for details on creating and managing tokens.

## Rate Limits

The API enforces rate limits to ensure fair usage:

- **Default**: 20 requests per second per client IP
- **Burst**: Up to 5x the base rate for short bursts

Exceeding the limit returns `429 Too Many Requests`.

## API Documentation

Interactive API documentation is available at:

```
https://api.forkline.dev/v1/docs
```

The OpenAPI specification can be downloaded from:

```
https://api.forkline.dev/v1/docs/openapi.json
```

## Pagination

List endpoints return paginated results. The API uses two pagination styles depending on the resource.

### Offset-based pagination

Used by **repositories** and **connectors**. Pass `offset` and `limit` query parameters.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `offset` | integer | `0` | Number of records to skip |
| `limit` | integer | `50` | Maximum records to return |

Response envelope:

```json
{
  "repositories": [...],
  "total": 142,
  "offset": 0,
  "limit": 50,
  "has_more": true
}
```

| Field | Type | Description |
|-------|------|-------------|
| `total` | integer | Total number of records matching the query |
| `offset` | integer | Current offset |
| `limit` | integer | Maximum records returned per page |
| `has_more` | boolean | `true` if more records exist beyond the current page |

To iterate: increment `offset` by `limit` until `has_more` is `false`.

### Page-based pagination

Used by **runners**. Pass `page` and `per_page` query parameters.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | `1` | Page number (1-indexed) |
| `per_page` | integer | `25` | Items per page (max 100) |

Response envelope:

```json
{
  "runners": [...],
  "total": 142
}
```

| Field | Type | Description |
|-------|------|-------------|
| `total` | integer | Total number of records matching the query |

To iterate: increment `page` until the returned array is empty or `page * per_page >= total`.

## Versioning

The API uses URL-based versioning. The current version is `v1`. Breaking changes are introduced in new major versions; non-breaking additions (new fields, new endpoints) are added to the current version.

## Changelog & Deprecation Policy

### Changelog

| Date | Change |
|------|--------|
| 2026-09-23 | Added `GET /v1/billing/credits`, `GET /v1/me/settings`, `PUT /v1/me/settings`, `GET /v1/runners/ids`. New scopes: `billing:read`, `user:write` |
| 2026-09-18 | Initial public API v1 release: repositories, runners, routines, models, analytics, connectors, tokens, secrets, custom providers |

### Deprecation policy

- **New major versions** (e.g. `v2`) are announced at least **90 days** before old versions are retired.
- **Endpoints** are deprecated by returning a `Sunset` header with the retirement date.
- **Response fields** are never removed within a major version. New fields may be added at any time — clients should ignore unknown fields.
- **Query parameters** follow the same rule: new parameters may be added, but existing ones are not removed within a major version.
- Deprecation notices are posted in this changelog and in the [Forkline status page](https://status.forkline.dev).

## Error Format

All errors return a consistent JSON envelope:

```json
{
  "error": "Human-readable description",
  "code": "ERROR_CODE"
}
```

See [Errors](https://forkline.dev/docs/reference/errors) for the full list of error codes and their meanings.

## What's Available

The public API exposes a curated set of endpoints for automation and integration:

- **Repositories**: Manage repositories and their configuration
- **Runners**: Start, stop, and monitor runners
- **Routines**: Create, update, and execute automation routines
- **Models**: List available AI models and providers
- **Analytics**: Access usage and performance data
- **Billing**: Read credit balances and subscription info
- **Connectors**: List git connectors (GitHub, GitLab, Forgejo)
- **API tokens**: Create, list, and revoke personal access tokens
- **Repository secrets**: Manage secrets for repository integrations
- **Custom providers**: Import and manage custom AI providers
- **User settings**: Read and update user preferences

See [Endpoints](https://forkline.dev/docs/reference/endpoints) for the complete list.

## What's Not Available

Some features remain on the web application and are not exposed on the public API v1:

- **Billing write operations**: Subscription plan changes and credit purchases (reading credit balances is available via `GET /v1/billing/credits`)
- **Connector creation and configuration**: Creating new connectors or modifying connector settings (use the web UI to onboard GitHub/GitLab/Forgejo integrations)
- **Account and identity management**: Profile and authentication settings (reading/updating user preferences is available via `/v1/me/settings`)
- **Real-time event streams**: SSE streams for live updates
- **Model favorites and recent models**: Favoriting models and viewing recently used models are available in the web UI only

These features require browser authentication on the main Forkline application. They are tracked as separate enhancement requests for future API versions.

### Repository preferences

Repository-level preferences (default runner size, default model, auto-fix CI, auto PR review, and related settings) **are** available via `PUT /v1/repositories/{id}`. See [Endpoints](https://forkline.dev/docs/reference/endpoints#repositories) for the full list of updatable fields.

## Quickstart

New to the API? Start with the [Integration Quickstart](https://forkline.dev/docs/reference/api-quickstart) for an end-to-end walkthrough.