Agent Jobs API Quickstart

Connect Colter to your existing workflow.

Colter is a hosted service. Your agent keeps its ordinary work and hires Colter for a defined job. The private pilot requires an approved account, permitted sources, a published service, a spending policy, and a designated customer reviewer.

Start a pilot if your account is not configured. If it is, use the scoped token and workspace slug supplied through your approved setup.

From an MCP client

Add a remote HTTP server at https://api.colter.ai/mcp in your client's MCP settings. Configure Authorization: Bearer YOUR_SCOPED_TOKEN and X-Colter-Workspace: YOUR_WORKSPACE through its protected connection settings.

List the available tools, discover your services, then use colter.purchase_job with a stable request key and maximum price. If your client only supports local stdio, ask the pilot team for the versioned Colter bridge and its installation instructions.

From an application

Follow the REST example below or use the versioned TypeScript/Python client supplied for your pilot. Public registry installation of this revision has not yet been verified. Keep credentials in your application's secret configuration, outside prompts and job input.

Connecting permits access to configured services; a purchase still requires spending authority. The customer reviewer accepts or rejects delivered work in Jobs.

For the account purchase flow, download the OpenAPI description or Postman collection. Import the collection, keep tokens in private environment settings, and send individual requests. Its default mode permits inspection; quote, purchase, acceptance, and customer review each require selecting the corresponding operation mode.

Use an approved account and scoped token.

The pilot team provisions your account, permitted sources, service, and spending policy. Your token needs services:read, quotes:read, quotes:write, and jobs:read for this flow. Use the workspace slug on every authenticated request.

export COLTER_TOKEN="your_scoped_token"
export COLTER_SPACE="your-workspace-slug"

curl https://api.colter.ai/api/v2/services \
  -H "Authorization: Bearer $COLTER_TOKEN" \
  -H "X-Colter-Workspace: $COLTER_SPACE"

Select the service key and version returned for your workspace. Public discovery at /api/catalog/v1/services requires no token.

Purchase within your spending authority.

Persist the request key before sending. The example limit is $2, not an advertised service price: one US dollar is 100,000,000 microcents. Replace the service key, version, and schema-valid input with the contract configured for your account.

curl -X POST https://api.colter.ai/api/v2/jobs/purchase \
  -H "Authorization: Bearer $COLTER_TOKEN" \
  -H "X-Colter-Workspace: $COLTER_SPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "service_key": "support_case_investigation",
    "service_version": 1,
    "correlation_id": "your-application-case-42",
    "input_payload": {"question": "What is the appropriate next step for case 42?"},
    "idempotency_key": "support-case-42-investigation-1",
    "max_price_microcents": 200000000
  }'

A successful response includes a durable job when spending is authorized. Otherwise it returns a quote requiring approval. A price above your limit is rejected. If manual approval is needed, inspect the quote and explicitly accept it through POST /api/v2/quotes/:quote_key/accept.

Use context_refs for permitted source references when they are not already configured on the service. Keep the caller's work ID in correlation_id and save the returned job ID with it. Neither field grants authority. After interruption, resume observation with the saved ID or retry the identical purchase payload and key.

MCP exposes the same operation as colter.purchase_job at https://api.colter.ai/mcp.

Retrieve evidence and review the delivery.

curl https://api.colter.ai/api/v2/jobs/JOB_KEY/outcome \
  -H "Authorization: Bearer $COLTER_TOKEN" \
  -H "X-Colter-Workspace: $COLTER_SPACE"

The job record carries execution status, submission, buyer resolution, and charge state. Completed execution does not mean the recommendation is correct. Review the evidence in Jobs and accept or reject the delivery. Pilot investigations remain advisory and bill after acceptance.

Need help now? Skip the catalog.

Two help desk verbs open a fixed-price job directly. POST /api/v2/help-desk/verify checks work your agent produced: send the work_product, the evidence behind it, and optionally the original request and a rubric. POST /api/v2/help-desk/escalate hands a decision to a person: send the question, your context, a proposed_action, and a deadline_seconds. A manager approves or declines before the deadline and the answer is delivered as the job outcome. Declined is an answer, not a failure. A missed deadline is delivered as unresolved, never silently.

curl -X POST https://api.colter.ai/api/v2/help-desk/escalate \
  -H "Authorization: Bearer $COLTER_TOKEN" \
  -H "X-Colter-Workspace: $COLTER_SPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "case-42-cancel-decision-1",
    "max_price_microcents": 100000000,
    "question": "Cancel this subscription? The customer is upset.",
    "context": {"account": "acct_42", "mrr": 120},
    "proposed_action": "Offer one free month before canceling.",
    "deadline_seconds": 3600
  }'

Both verbs take the same idempotency_key and max_price_microcents as a purchase and return the same job shape plus a ticket block. MCP exposes them as colter.verify and colter.escalate.

Retry the same purchase. Repeat only proven work.

Retry with the identical key and payload after a network failure. Changing the request with that key conflicts. HTTP and polling timeouts do not cancel the job. Use its explicit cancellation action when needed; inspect the resulting state before buying a replacement.

Once a sample has been accepted, save it in Automations. New schedules and authenticated events buy the same pinned service through the same spending policy. They start paused for review.

Purchase one bounded job.