Skip to content
GOCUX
Documentation
GOCUX / Documentationtask api

Integrate task completion with your application

Build completion handling around task reads when a generic outbound webhook is not part of the contract.

Build completion handling around task reads when a generic outbound webhook is not part of the contract.

Practical procedure

  1. Store the work-order identifier and poll its read endpoint with bounded backoff, or observe its event stream while the client is connected.
  2. When the task reaches a terminal state, load its attachments and evaluate acceptance criteria. Persist your own delivery record before notifying another application.
  3. If your adapter sends an external webhook, authenticate and deduplicate that delivery in the adapter. Keep its delivery status separate from GoCux task completion.

Use a governed work order

A GoCux work order records an outcome, context and acceptance criteria. Use it for durable work that needs the optional Cloud Worker, rather than assuming that every chat turn starts a background job. Select the project and data classification when creating the request. Keep the returned work-order identity so progress, decisions and attachments remain tied to the same operation.

Contract example

Developer examples below describe routes on an authorized, configured GoCux control-plane base URL. They are request shapes or operation references, not claims that a particular public hostname exposes the API. Use the workspace for the corresponding human workflow; availability and permissions depend on the actual deployment.

POST /work-orders — example request body; supply an operation-specific Idempotency-Key

{
  "goal": "Review the supplied project notes",
  "body": "Use only the provided project context.",
  "acceptance": [
    "Identify claims with their supporting source",
    "List unanswered questions separately"
  ],
  "dataClassification": "public",
  "projectId": "project-id",
  "max_wall_seconds": 300,
  "max_tool_calls": 20
}

Inspect the result

A recorded or accepted work order is not proof of completed execution. Read its state, progress and attachments through the task views. Review the output against the acceptance criteria before using it. If a structured result was requested, inspect its validation state separately from the narrative answer.

What to keep explicit

This is an adapter pattern, not a claim that GoCux accepts an arbitrary callback URL in a task request. An external notification failure must not rerun completed work.

Handle incomplete and refused work

A missing worker or an unavailable dispatch ledger can refuse durable execution while normal chat remains independent. Reuse an operation key only for the same request. After a lost response, reconcile the original operation rather than blindly dispatching new work. A configured maxCost is recorded as context; the work-order schema does not claim it is an enforced monetary ceiling.

Bring this workflow into your workspace.

Set the scope. Review the evidence. Approve the steps that need it.

Open the workspace

Keep exploring