API reference

The Agent API runs coding and automation agents for your app in isolated workspaces. Every request goes to https://api.forgeling.io/v1 over HTTPS with JSON bodies and an API key as a bearer token (Authorization: Bearer fgk_...); the key's scopes decide which operations it may call. Errors, pagination, idempotency, versioning, rate limits and the signed webhooks are described in conventions.

Read the conventions first: errors, pagination, idempotency and versioning work the same way on every endpoint. The OpenAPI document this page is generated from is /openapi/v1.json.

App

Read the app the API key belongs to: its tier, quotas, usage and the key itself.

GET /v1/app

Get the calling app

Scope: any valid key

Parameters

Responses

Webhooks

Register the endpoints that receive signed events and the endpoint that refreshes run credentials, and inspect or retry deliveries.

DELETE /v1/app/credential_refresh

Remove the credential-refresh endpoint

Scope: webhooks:write

Parameters

Responses

GET /v1/app/credential_refresh

Get the credential-refresh endpoint

Scope: webhooks:read

Parameters

Responses

PUT /v1/app/credential_refresh

Set the credential-refresh URL

Scope: webhooks:write

Parameters

Request body

Responses

POST /v1/app/credential_refresh/rotate_secret

Give the credential-refresh endpoint a new secret; the old one signs for another 24 hours

Scope: webhooks:write

Idempotency-Key: optional

Parameters

Responses

GET /v1/webhook_deliveries

List webhook deliveries, newest first

Scope: webhooks:read

Parameters

Responses

POST /v1/webhook_deliveries/{id}/retry

Send a delivery again now

Scope: webhooks:write

Idempotency-Key: optional

Parameters

Responses

GET /v1/webhook_endpoints

List webhook endpoints

Scope: webhooks:read

Parameters

Responses

POST /v1/webhook_endpoints

Register a webhook endpoint

Scope: webhooks:write

Idempotency-Key: optional

Parameters

Request body

Responses

DELETE /v1/webhook_endpoints/{id}

Delete a webhook endpoint

Scope: webhooks:write

Parameters

Responses

GET /v1/webhook_endpoints/{id}

Get a webhook endpoint

Scope: webhooks:read

Parameters

Responses

PATCH /v1/webhook_endpoints/{id}

Change a webhook endpoint, or enable it again

Scope: webhooks:write

Parameters

Request body

Responses

POST /v1/webhook_endpoints/{id}/rotate_secret

Give a webhook endpoint a new secret; the old one signs for another 24 hours

Scope: webhooks:write

Idempotency-Key: optional

Parameters

Responses

POST /v1/webhook_endpoints/{id}/test

Send a ping event to this endpoint alone

Scope: webhooks:write

Idempotency-Key: optional

Parameters

Responses

Bundles

Publish, list and yank the versions of the agent bundles that runs are created from.

GET /v1/bundles

List bundles

Scope: bundles:read

Parameters

Responses

GET /v1/bundles/{name}/versions

List the versions of a bundle

Scope: bundles:read

Parameters

Responses

POST /v1/bundles/{name}/versions

Publish a version of a bundle from an inline spec

Scope: bundles:write

Idempotency-Key: optional

Parameters

Request body

Responses

GET /v1/bundles/{name}/versions/{v}

Get a version of a bundle

Scope: bundles:read

Parameters

Responses

POST /v1/bundles/{name}/versions/{v}/yank

Yank a version: it starts no new runs

Scope: bundles:write

Idempotency-Key: optional

Parameters

Responses

Workspaces

Create and manage the workspaces your end users work in, and the model credential each uses.

GET /v1/workspaces

List workspaces

Scope: workspaces:read

Parameters

Responses

POST /v1/workspaces

Create a workspace, or return the live one for its external_id

Scope: workspaces:write

Idempotency-Key: optional

Parameters

Request body

Responses

DELETE /v1/workspaces/{ws}

Delete a workspace and everything in it

Scope: workspaces:write

Parameters

Responses

GET /v1/workspaces/{ws}

Get a workspace

Scope: workspaces:read

Parameters

Responses

PATCH /v1/workspaces/{ws}

Update a workspace's name, time zone or metadata

Scope: workspaces:write

Parameters

Request body

Responses

DELETE /v1/workspaces/{ws}/model_credential

Remove a workspace's model credential

Scope: credentials:write

Parameters

Responses

GET /v1/workspaces/{ws}/model_credential

Get a workspace's model credential

Scope: credentials:read

Parameters

Responses

PUT /v1/workspaces/{ws}/model_credential

Set a workspace's model credential

Scope: credentials:write

Parameters

Request body

Responses

POST /v1/workspaces/{ws}/resume

Resume a suspended workspace

Scope: workspaces:write

Idempotency-Key: optional

Parameters

Responses

POST /v1/workspaces/{ws}/suspend

Suspend a workspace: no new runs, and its live runs end

Scope: workspaces:write

Idempotency-Key: optional

Parameters

Responses

Runs

Create a run in a workspace, follow it through its life, set its secrets and end it.

DELETE /v1/runs/{run}

Delete a run

Scope: runs:write

Parameters

Responses

GET /v1/runs/{run}

Get a run

Scope: runs:read

Parameters

Responses

PATCH /v1/runs/{run}

Raise a run's budget, extend its expiry or replace its metadata

Scope: runs:write

Parameters

Request body

Responses

POST /v1/runs/{run}/cancel

Cancel a run

Scope: runs:write

Idempotency-Key: optional

Parameters

Responses

POST /v1/runs/{run}/complete

Complete a run

Scope: runs:write

Idempotency-Key: optional

Parameters

Responses

DELETE /v1/runs/{run}/secrets/{name}

Remove a run secret

Scope: runs:write

Parameters

Responses

PUT /v1/runs/{run}/secrets/{name}

Set a run secret

Scope: runs:write

Parameters

Request body

Responses

GET /v1/workspaces/{ws}/runs

List a workspace's runs

Scope: runs:read

Parameters

Responses

POST /v1/workspaces/{ws}/runs

Create a run

Scope: runs:write

Idempotency-Key: required

Parameters

Request body

Responses

Turns

Post work to a run, read what came of it and cancel it.

POST /v1/runs/{run}/turns

Post a turn to a run

Scope: runs:write

Idempotency-Key: required

Parameters

Request body

Responses

GET /v1/turns

Find a run's turn by the Idempotency-Key it was posted with

Scope: runs:read

Parameters

Responses

GET /v1/turns/{trn}

Get a turn

Scope: runs:read

Parameters

Responses

POST /v1/turns/{trn}/cancel

Cancel a turn

Scope: runs:write

Idempotency-Key: optional

Parameters

Responses

Approvals

List the tool uses that agents are waiting on, and allow or deny them.

GET /v1/approvals

List approvals

Scope: approvals:read

Parameters

Responses

POST /v1/approvals/{apr}/decision

Allow or deny an approval

Scope: approvals:write

Idempotency-Key: optional

Parameters

Request body

Responses

Events

Read a run's replayable event log or the app-wide feed, or stream a run's events live.

GET /v1/events

List the app's events

Scope: events:read

Parameters

Responses

GET /v1/runs/{run}/events

List a run's events

Scope: events:read

Parameters

Responses

GET /v1/runs/{run}/events/stream

Stream a run's events

Scope: events:read

Parameters

Responses

Files

List the files a run produced and download them through short-lived signed links.

GET /v1/files/{f}

Get an output file

Scope: files:read

Parameters

Responses

GET /v1/files/{f}/content

Download an output file

Scope: files:read

Parameters

Responses

GET /v1/runs/{run}/files

List a run's output files

Scope: files:read

Parameters

Responses

Usage

Read the model usage and cost of your app, by day or by run.

GET /v1/usage

Usage by day or by run

Scope: usage:read

Parameters

Responses

Calls to your app

These are the requests Forgeling sends to your app. credential.refresh is answered with a body; the others are events, and each links to its entry in the event catalog.

credential.refresh

The credential.refresh call

Request body

Responses

• approval.requested: The approval.requested event
• approval.resolved: The approval.resolved event
• budget.warning: The budget.warning event
• bundle.version_ready: The bundle.version_ready event
• bundle.version_rejected: The bundle.version_rejected event
• message.completed: The message.completed event
• output.created: The output.created event
• ping: The ping event
• run.cancelled: The run.cancelled event
• run.completed: The run.completed event
• run.expired: The run.expired event
• run.failed: The run.failed event
• run.idle: The run.idle event
• run.provisioning: The run.provisioning event
• run.queued: The run.queued event
• run.ready: The run.ready event
• run.resumed: The run.resumed event
• run.running: The run.running event
• run.suspended: The run.suspended event
• secret.refresh_failed: The secret.refresh_failed event
• tool.completed: The tool.completed event
• tool.started: The tool.started event
• turn.cancelled: The turn.cancelled event
• turn.completed: The turn.completed event
• turn.failed: The turn.failed event
• turn.interrupted: The turn.interrupted event
• turn.queued: The turn.queued event
• turn.started: The turn.started event
• workspace.credential_invalid: The workspace.credential_invalid event