API reference / REST v1

Jobs & webhooks

Poll results, stream job events, and manage webhook delivery.

All paths below are relative to https://www.agentseo.dev/api/v1. Send your key in x-api-key. Set AGENTSEO_API_KEY in your environment before running the examples. IDs and results are illustrative.

Async result handling · Errors and limits · OpenAPI contract

GET`/webhooks/endpoints`

List the webhook endpoints registered for your workspace.

GET /webhooks/endpoints example

curl https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: $AGENTSEO_API_KEY"

POST`/webhooks/endpoints`

Create a signed webhook endpoint for async job delivery. The signing secret is returned once on create.

Request fields · required fields are labeled
Name	Type	Description
`url`Required	string	HTTPS endpoint that will receive webhook POSTs
`events`	array	Any of job.completed, job.failed, project.budget_warning, or project.budget_exceeded

POST /webhooks/endpoints example

curl -X POST https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/agentseo","events":["job.completed","project.budget_warning","project.budget_exceeded"]}'

PATCH`/webhooks/endpoints/{id}`

Update a webhook endpoint in place. Use this to rotate target URLs, event subscriptions, descriptions, or to pause delivery with is_active=false.

Request fields · required fields are labeled
Name	Type	Description
`id`Required	string	Webhook endpoint ID
`url`	string	New HTTPS target URL
`description`	string	Optional human-readable label
`events`	array	Any of job.completed, job.failed, project.budget_warning, or project.budget_exceeded
`is_active`	boolean	Set false to pause deliveries without deleting the endpoint

PATCH /webhooks/endpoints/{id} example

curl -X PATCH https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Primary production hook","is_active":false}'

DELETE`/webhooks/endpoints/{id}`

Delete a webhook endpoint. This stops future deliveries to that target but does not remove historical delivery records.

Request fields · required fields are labeled
Name	Type	Description
`id`Required	string	Webhook endpoint ID

DELETE /webhooks/endpoints/{id} example

curl -X DELETE https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: $AGENTSEO_API_KEY"

GET`/webhooks/deliveries`

Inspect recent webhook delivery attempts, response codes, and failure reasons.

Query parameters · required fields are labeled
Name	Type	Description
`limit`	integer	Number of rows to return (default: 25, max: 100)
`status`	string	Filter by pending, delivered, or failed
`endpoint_id`	string	Filter to one webhook endpoint ID
`project_id`	string	Filter deliveries for one project, including budget alerts
`event_type`	string	Filter one event type such as project.budget_warning or job.completed

GET /webhooks/deliveries example

curl https://www.agentseo.dev/api/v1/webhooks/deliveries?limit=25&project_id=client-alpha&event_type=project.budget_exceeded \
  -H "x-api-key: $AGENTSEO_API_KEY"

POST`/webhooks/deliveries/{id}/retry`

Retry a failed webhook delivery without re-running the underlying job.

Request fields · required fields are labeled
Name	Type	Description
`id`Required	string	Webhook delivery ID

POST /webhooks/deliveries/{id}/retry example

curl -X POST https://www.agentseo.dev/api/v1/webhooks/deliveries/123e4567-e89b-12d3-a456-426614174000/retry \
  -H "x-api-key: $AGENTSEO_API_KEY"

GET`/jobs/{id}`

Check the status of an async job. Returns public progress, attempts, result, error, and attribution context.

Query parameters · required fields are labeled
Name	Type	Description
`id`Required	string	Job ID from 202 response

GET /jobs/{id} example

curl https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: $AGENTSEO_API_KEY"

GET`/jobs/{id}/events`

Open an SSE stream for live job updates. Emits events such as job.open, job.status, job.done, and job.failed.

Query parameters · required fields are labeled
Name	Type	Description
`id`Required	string	Job ID from a queued async request

GET /jobs/{id}/events example

curl -N https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/events \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Accept: text/event-stream"

← All endpoints

GET/webhooks/endpoints

POST/webhooks/endpoints

PATCH/webhooks/endpoints/{id}

DELETE/webhooks/endpoints/{id}

GET/webhooks/deliveries

POST/webhooks/deliveries/{id}/retry

GET/jobs/{id}

GET/jobs/{id}/events