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_….
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
successandresult: whether the end check passed, and the answer in words.outcome:done,partial(something to show, not all of it confirmed) orfailed; a run that didn't pass has areportwith its answer, what is done, what is not and why it stopped.paused: trueandnexton a task that stopped to wait:continue(send a follow-up, e.g. "Continue"),sign_in(a follow-up with a login) or, withoutpaused,retry_region(a follow-up with anotherregion).erroron 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:
{
"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"
}
}{
"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:
{
"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).
| code | Status | Meaning |
|---|---|---|
invalid_request | 400 | A field is missing or wrong: fields lists each one with its path. |
invalid_schema | 400 | outputSchema can't be used: the message says why. |
unauthorized | 401 | No key, a revoked key, or a signed-out session. |
no_credits / allocation_used / org_limit | 402 | Refused for money before it starts: the message says whom to ask. |
admins_only | 403 | Only the organization's admins may do this. |
not_found | 404 | No such job, task or item of yours. |
not_running | 409 | The job isn't running, or isn't waiting on that question. |
one_session / identity_busy | 409 | One task at a time per person, key and identity. |
shared_project / personal_project | 409 | This belongs in the other kind of project. |
rate_limited / queue_full / start_rate | 429 | Wait 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.