DocsAPI

REST API

Run tasks from your own code: send one, follow it, get its answer, as JSON in your own shape when you give a schema.

Start a task

Every request takes an organization API key (Org settings → API keys) as Authorization: Bearer pf_….

Requestbash
curl -X POST https://pilotfish-be.gai.ventures/jobs \
  -H "Authorization: Bearer pf_YOUR_KEY" -H "content-type: application/json" \
  -d '{"task":"Find the price of the Logitech MX Keys on amazon.com","outputSchema":{"type":"object","properties":{"product":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"}},"required":["product","price","currency"],"additionalProperties":false}}'

The answer is 201 with the job: id, status, url (the job in the API), appUrl (its page in the app, to watch it or take the browser) and answerUrl (where a person answers what the task asks). POST /jobs/:id/followup and POST /saved-tasks/:id/run answer the same way.

Follow it

GET /jobs/:id until status is done, failed or cancelled, or set webhookUrl and wait for job.finished. While it runs, next: "answer" means a person must answer its question (send them answerUrl).

The result

  • success and result: whether the end check passed, and the answer in words.
  • outcome: done, partial (something to show, not all of it confirmed) or failed; a run that didn't pass has a report with its answer, what is done, what is not and why it stopped.
  • paused: true and next on a task that stopped to wait: continue (send a follow-up, e.g. "Continue"), sign_in (a follow-up with a login) or, without paused, retry_region (a follow-up with another region).
  • error on a failed job: its code, then what happened (fleet_busy: …, interrupted: …).

Structured output

Give outputSchema, a JSON Schema whose root has type: "object" (at most 16 KB, local $refs only), on POST /jobs, a follow-up (omitted keeps the session's; null drops it) or a saved task's options. The result then has data, the answer as JSON that matches it, or dataError saying why there is none:

Resultjson
{
  "success": true,
  "outcome": "done",
  "result": "The Logitech MX Keys is $109.99 on amazon.com.",
  "data": {
    "product": "Logitech MX Keys",
    "price": 109.99,
    "currency": "USD"
  }
}
When it doesn't fitjson
{
  "dataError": {
    "code": "schema_mismatch",
    "errors": [
      "price: must be number"
    ]
  }
}

schema_mismatch lists up to 5 errors; no_answer means the run gave no answer to make JSON from. The answer in words is always in result. A schema adds one small model call to a task whose browser agent didn't already return matching JSON, and one more when that call's JSON doesn't fit.

Errors

Every error is JSON with a code:

Errorjson
{
  "error": "outputSchema: the schema's root must have type \"object\"",
  "code": "invalid_schema",
  "fields": [
    {
      "path": "outputSchema",
      "message": "the schema's root must have type \"object\""
    }
  ]
}

fields lists each wrong field; retryAfterS comes with every 429 (and a Retry-After header); docs links the fix when a person must act (add credits, ask an admin). Some carry figures of their own (balanceUsd, threadId).

codeStatusMeaning
invalid_request400A field is missing or wrong: fields lists each one with its path.
invalid_schema400outputSchema can't be used: the message says why.
unauthorized401No key, a revoked key, or a signed-out session.
no_credits / allocation_used / org_limit402Refused for money before it starts: the message says whom to ask.
admins_only403Only the organization's admins may do this.
not_found404No such job, task or item of yours.
not_running409The job isn't running, or isn't waiting on that question.
one_session / identity_busy409One task at a time per person, key and identity.
shared_project / personal_project409This belongs in the other kind of project.
rate_limited / queue_full / start_rate429Wait retryAfterS seconds, then try again.

Webhooks

job.finished carries the job's status and the same result fields: success, result, outcome, report, blocked, signIn, paused, next, data or dataError, and error. Each delivery is signed with your organization's secret in Pilotfish-Signature.

The managed MCP takes the same schema as output_schema and replies Data: {…} with the JSON as structured content.