View as Markdown

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:

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

See 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:

{
  "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:

{
  "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.

Error Format

All errors return a consistent JSON envelope:

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

See 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 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 for the full list of updatable fields.

Quickstart

New to the API? Start with the Integration Quickstart for an end-to-end walkthrough.