/\ ATFGraph /docs
README Downloads
HTTP API & schemas / ATFGraph
Framework reference

This article is retained from the existing framework docs. Self-hosting commands and server-admin access differ from the managed CLI workflow. Start with Get started for the installed product.

Worker API

Enroll outbound workers, claim and renew tasks, report progress/results and drain. Operators can also inspect the enrolled fleet.

Operations

OperationMethodPath
bindSessionPOST/api/v2/sessions/bind
claimTaskPOST/api/v2/worker/claim
completeTaskPOST/api/v2/worker/complete
drainWorkerPOST/api/v2/worker/drain
enrollWorkerPOST/api/v2/worker/enroll
reportProgressPOST/api/v2/worker/progress
renewLeasePOST/api/v2/worker/renew
resumeTaskPOST/api/v2/worker/resume
suspendTaskPOST/api/v2/worker/suspend
listWorkersGET/api/v2/workers

bindSession

POST /api/v2/sessions/bind

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.bind_session()

Request body

BindSession (required)

{
  "id": "string",
  "lease_token": "string",
  "session_id": "string",
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200SessionBindingSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
410ErrorResponseSession was deleted (session_deleted)
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "bound": false,
  "session_id": "string"
}

claimTask

POST /api/v2/worker/claim

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.claim_task()

Request body

WorkerId (required)

{
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200ClaimSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "capacity": 0,
  "draining": false,
  "task": {
    "attempt": 0,
    "capability": "string",
    "deadline_at": 0,
    "emitter": {
      "emitter_id": "string",
      "event_id": "string",
      "event_type": "string",
      "idempotency_key": "string",
      "managed_by": "string",
      "received_at": "string",
      "source": "string"
    },
    "id": "string",
    "input": {},
    "kind": "string",
    "label": "string",
    "lease_expires_at": 0,
    "lease_token": "string",
    "max_attempts": 0,
    "namespace": "string",
    "parent_id": "string",
    "parent_step_id": "string",
    "principal": "string",
    "root_id": "string",
    "session_id": "string",
    "step_id": "string",
    "target": "string",
    "timeout_seconds": 0,
    "version": "string"
  }
}

completeTask

POST /api/v2/worker/complete

Requires: worker role

Provide exactly one of output or error. Stale, expired or cancelled leases conflict. Retryable errors are retried only within the registered max_attempts policy.

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.complete_task()

Request body

CompleteTask (required)

{
  "id": "string",
  "lease_token": "string",
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200AcceptedSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "accepted": false
}

drainWorker

POST /api/v2/worker/drain

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.drain_worker()

Request body

WorkerId (required)

{
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200DrainingSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "draining": false
}

enrollWorker

POST /api/v2/worker/enroll

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.enroll_worker()

Request body

EnrollWorker (required)

{
  "label": "string",
  "version": "string"
}

Responses

StatusBodyMeaning
201WorkerSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 201

{
  "capacity": 0,
  "label": "string",
  "lease_seconds": 0,
  "version": "string",
  "worker_id": "string"
}

reportProgress

POST /api/v2/worker/progress

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.report_progress()

Request body

ProgressTask (required)

{
  "data": {},
  "id": "string",
  "lease_token": "string",
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200AcceptedSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "accepted": false
}

renewLease

POST /api/v2/worker/renew

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.renew_lease()

Request body

Lease (required)

{
  "id": "string",
  "lease_token": "string",
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200LeaseRenewalSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "cancel_requested": false,
  "lease_expires_at": 0
}

resumeTask

POST /api/v2/worker/resume

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.resume_task()

Request body

Lease (required)

{
  "id": "string",
  "lease_token": "string",
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200ResumedSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "resumed": false
}

suspendTask

POST /api/v2/worker/suspend

Requires: worker role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.suspend_task()

Request body

Lease (required)

{
  "id": "string",
  "lease_token": "string",
  "worker_id": "string"
}

Responses

StatusBodyMeaning
200SuspendedSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "suspended": false
}

listWorkers

GET /api/v2/workers

Requires: invoke role

Generated Python client internals: atfgraph._generated.api.worker_api.WorkerApi.list_workers()

Parameters

ParameterInRequiredType
labelquerynostring
limitquerynointeger

Responses

StatusBodyMeaning
200WorkerListSuccessful operation
400ErrorResponseStructured API error
401ErrorResponseMissing or invalid credentials
403ErrorResponseRole or ownership denied
404ErrorResponseResource unavailable to this identity
409ErrorResponseRevision, idempotency, immutable version or lease conflict
413ErrorResponseStructured API error
422ErrorResponseCapability input/output schema violation
429ErrorResponseCapacity exceeded
500ErrorResponseStructured API error
503ErrorResponseStructured API error

Example response 200

{
  "items": [
    {
      "capacity": 0,
      "draining": false,
      "enrolled_at": 0,
      "expired_leases": 0,
      "id": "string",
      "label": "string",
      "last_seen_age_ms": 0,
      "last_seen_at": 0,
      "principal": "string",
      "state": "string",
      "tasks_in_flight": 0,
      "version": "string"
    }
  ],
  "truncated": false
}
ATFGraph documentationHosted workflow · Framework reference