Signal API
Onboarding operations as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Onboarding operations

Poll automatic project and location onboarding with one shared operation endpoint.

GET
/onboarding-operations/{id}

Returns safe progress for one project or location onboarding operation.

Parameters

Path parameters

iduuid

Onboarding operation identifier returned when a project or location is created with start: true.

Required
Response

OnboardingOperation response envelope

id:uuidstatus:queued | running | waiting_visibility | waiting_diagnosis | succeeded | partial | failed | cancelledresource_type:project | locationresource_id:uuidcurrent_step:string | nullprogress:objectmessage:stringerror:object | nullsteps:OnboardingStep[]status_url:string
iduuid

Onboarding operation identifier.

statusqueued | running | waiting_visibility | waiting_diagnosis | succeeded | partial | failed | cancelled

Current operation state.

resource_typeproject | location

Resource being onboarded.

resource_iduuid

Project or location identifier.

current_stepstring | null

Current onboarding step, or null before work begins.

progressobject

Completed and total step counts.

messagestring

Stable, customer-safe status message.

errorobject | null

Stable public error code and message for failed or partial operations.

stepsOnboardingStep[]

Public status for each onboarding step.

status_urlstring

Relative URL for polling this operation.

PollingPoll status_url until the status is succeeded, partial, failed, or cancelled.
Safe errorsStatus and step errors use fixed public codes and messages. Provider names, exception text, and internal metadata are never returned.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/onboarding-operations/1c07ea43-a8fe-4d07-8741-9c624d67b466' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "onboarding_operation": {
    "id": "1c07ea43-a8fe-4d07-8741-9c624d67b466",
    "status": "running",
    "resource_type": "location",
    "resource_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
    "current_step": "topics",
    "progress": {
      "completed": 1,
      "total": 6
    },
    "message": "Onboarding is in progress.",
    "steps": [
      {
        "key": "enrichment",
        "status": "succeeded"
      },
      {
        "key": "topics",
        "status": "running"
      },
      {
        "key": "prompts",
        "status": "pending"
      },
      {
        "key": "competitors",
        "status": "pending"
      },
      {
        "key": "visibility",
        "status": "pending"
      },
      {
        "key": "diagnosis",
        "status": "pending"
      }
    ],
    "status_url": "/v1/onboarding-operations/1c07ea43-a8fe-4d07-8741-9c624d67b466",
    "created_at": "2026-08-04T15:00:00Z",
    "started_at": "2026-08-04T15:00:01Z",
    "updated_at": "2026-08-04T15:00:03Z"
  }
}
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

400invalid_request

The operation ID is not a UUID.

401invalid_api_key

The API key is absent, invalid, expired, or revoked.

403forbidden

The API key lacks read or write access for the resource being onboarded.

404not_found

The operation does not exist or is outside the API key scope.