Use the public API

Forge's public REST API lets you pull run data into your own systems — dashboards, reporting tools, scripts, or downstream pipelines. This guide covers authentication and the core endpoints.

Step 1: Create an API key

Go to Settings → Integrations → API Keys → Create key. Give it a descriptive name (e.g. "Dashboard integration" or "CI pipeline"). Copy the key — it is shown only once. If you lose it, you will need to rotate it by creating a new one and revoking the old one.

Step 2: Authenticate requests

Pass the API key as a Bearer token in the Authorization header:

curl https://forge.shanova.se/api/v1/runs \
  -H "Authorization: Bearer forge_key_abc123xyz"

GET /api/v1/runs

Returns your run history, paginated.

GET https://forge.shanova.se/api/v1/runs

# Query parameters
?limit=20          # Results per page. Default 20, max 100.
?status=completed  # Filter: queued, running, completed, failed, blocked
?team_id={id}      # Filter by team ID

# Response
{
  "runs": [
    {
      "id": "run_abc123",
      "title": "Market Entry Analysis — DACH",
      "brief": "Analyse the DACH market for...",
      "status": "completed",
      "team_id": "team_xyz456",
      "created_at": "2026-01-15T09:00:00Z",
      "completed_at": "2026-01-15T09:08:42Z",
      "outputs_count": 8
    }
  ],
  "total": 142
}

Pagination

Use the limit parameter and the total field to paginate. If total is larger than your result count, request the next page using an offset or cursor parameter.

# First page
GET /api/v1/runs?limit=20

# If total > 20, request next page
GET /api/v1/runs?limit=20&offset=20