Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Codai Ro Jobs API
version: '1'
description: 'Operations tagged Jobs across 2 of this provider''s published API definitions: codai-ro-resolve-openapi.json, codai-ro-resolve-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://resolve.codai.ro
description: Production (private beta)
security:
- bearerAuth: []
tags:
- name: Jobs
description: Submit, poll and accept resolve jobs. Every job is scoped to the user that owns the API key.
paths:
/v1/resolve/jobs:
post:
operationId: createResolveJob
tags:
- Jobs
summary: Submit a repository + issue for triage
description: 'Creates a job and runs **triage inline** (bounded by the request timeout). Exactly one of
`issue_url` or `issue_text` is required; inline text wins, otherwise the public GitHub
issue is fetched without a token (a private repo → `400`).
Outcomes:
- **`201`** with `status: quoted` — a paid tier was quoted; call `/accept` to start.
- **`201`** with `status: accepted` — you still had free-tier resolves; the job was
auto-accepted and dispatched immediately (`tier: free`, `quote_micro_usd: 0`).
- **`200`** with `status: declined` — triage refused (feature request, unclear spec,
needs credentials, or triage was unavailable — retry later).
Abuse limits are checked *before* the body is parsed, so a `429` can arrive for an
otherwise valid payload. The free-tier claim is atomic per user, so parallel submissions
across several keys cannot exceed the 3 free resolves.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveIntake'
responses:
'200':
description: Job created but declined by triage.
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveDeclined'
'201':
description: Job created and quoted (or auto-accepted on the free tier).
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveQuote'
'400':
$ref: '#/components/responses/ResolveBadRequest'
'401':
$ref: '#/components/responses/ResolveUnauthorized'
'429':
$ref: '#/components/responses/ResolveRateLimited'
'500':
$ref: '#/components/responses/ResolveInternalError'
get:
operationId: listResolveJobs
tags:
- Jobs
summary: List your jobs
description: 'Your jobs, newest first (`created_at` desc, then `id` desc), each in the same shape as
`GET /v1/resolve/jobs/{id}`. Page with `next_cursor`: pass it back as `cursor` until it is
`null`. Before answering, the server sweeps orphaned `accepted`/`running` jobs into `error`.
An unknown `status` value, a malformed `cursor` or an out-of-range `limit` is a `400`.'
parameters:
- name: status
in: query
required: false
description: Comma-separated statuses to keep, e.g. `running,quoted`. Omitted = every status.
schema:
type: string
examples:
- resolved,failed
- name: limit
in: query
required: false
description: Page size, 1–100 (default 20).
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: cursor
in: query
required: false
description: Opaque cursor from the previous page's `next_cursor`.
schema:
type: string
responses:
'200':
description: One page of jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveJobList'
'400':
$ref: '#/components/responses/ResolveBadRequest'
'401':
$ref: '#/components/responses/ResolveUnauthorized'
servers:
- url: https://resolve.codai.ro
description: Production (private beta)
/v1/resolve/jobs/{id}:
get:
operationId: getResolveJob
tags:
- Jobs
summary: Get job status, quote and proof pointer
description: 'Returns the current status of a job you own. Poll this after accepting: when the job
reaches `resolved`, `attestation_id` and `attestation_url` point at the public proof.
Before answering, the server sweeps orphaned `accepted`/`running` jobs into `error`, so
you never poll a zombie. A job owned by another user is reported as `404` (not `403`).'
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Job found.
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveJob'
'401':
$ref: '#/components/responses/ResolveUnauthorized'
'404':
$ref: '#/components/responses/ResolveNotFound'
servers:
- url: https://resolve.codai.ro
description: Production (private beta)
/v1/resolve/jobs/{id}/accept:
post:
operationId: acceptResolveJob
tags:
- Jobs
summary: Accept a paid quote and start the job
description: 'Moves a `quoted` job to `accepted` and dispatches it to the worker (Cloud Run Job, or
in-process in soft mode). Only `quoted` jobs can be accepted — any other status returns
`409` with the current status in the message. Free-tier jobs are auto-accepted at
submission and never need this call. No request body.
In the same transaction the quote is **held on your wallet** (EUR, 1:1 with the USD
price). The hold is kept on a verified fix and refunded in full otherwise. If the
balance is short, the answer is `402 insufficient_funds` with the shortfall and a
top-up link, and the job stays `quoted` — top up, then call `/accept` again.
Payment precedence: `intro` (first paid job, €1 hold) > `credit` (t7 only, one fix credit,
no wallet hold) > `wallet` (hold of the list price). `paid_with` in the response says which
was used; `held_micro_eur` is the wallet amount held (`0` for a credit). For a `t7` job the
`402` also carries `bundle_url` (10 fixes for €49).'
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Job accepted and dispatched.
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveAccepted'
'401':
$ref: '#/components/responses/ResolveUnauthorized'
'402':
$ref: '#/components/responses/ResolveInsufficientFunds'
'404':
$ref: '#/components/responses/ResolveNotFound'
'409':
$ref: '#/components/responses/ResolveConflict'
servers:
- url: https://resolve.codai.ro
description: Production (private beta)
/v1/resolve/balance:
get:
operationId: getResolveBalance
tags:
- Jobs
summary: Fix credits, intro availability and wallet balance
description: 'Returns what you can pay with right now: the fix-credit balance (usable only on `t7`
jobs), whether the €1 intro price is still available (no verified paid job yet and no
other intro job in flight) and the wallet balance in EUR micros.'
responses:
'200':
description: Current balance.
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveBalance'
'401':
$ref: '#/components/responses/ResolveUnauthorized'
servers:
- url: https://resolve.codai.ro
description: Production (private beta)
webhooks:
resolveJobEvent:
post:
operationId: resolveJobWebhook
tags:
- Jobs
summary: Job event delivered to your callback_url
description: 'Sent to the `callback_url` given on intake when the job reaches a decision point:
`job.quoted`, `job.declined`, `job.resolved`, `job.failed` or `job.error`.
**Signature:** `x-codai-signature: t=,v1=` where
`v1 = HMAC-SHA256(callback_secret, ".")` in lowercase hex. Verify against
the raw request bytes (before JSON parsing), compare in constant time and reject stale
timestamps (the SDKs use a 300 s tolerance): `verifyResolveWebhook` (TypeScript) and
`verify_resolve_webhook` (Python).
**Delivery:** up to 3 attempts (backoff 1 s, 4 s) on `5xx`, `429` or a network error;
any other non-2xx stops retrying. 10 s timeout per attempt; redirects are not followed.
`x-codai-delivery` (`:`) is stable across retries — use it to deduplicate.
Delivery never changes job state or billing; poll `GET /v1/resolve/jobs/{id}` as the
source of truth.'
security: []
parameters:
- name: x-codai-event
in: header
required: true
description: Event name, same as `event` in the body.
schema:
$ref: '#/components/schemas/ResolveWebhookEventName'
- name: x-codai-delivery
in: header
required: true
description: Idempotency key `<jobId>:<event>`, identical on every retry.
schema:
type: string
examples:
- 1f2c1a3e-8d4b-4f8e-9a1b-0c2d3e4f5a6b:job.resolved
- name: x-codai-signature
in: header
required: true
description: '`t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`.'
schema:
type: string
examples:
- t=1790000000,v1=5d41402abc4b2a76b9719d911017c592ae2f1f7c0e8b1f6d3b8a8c1e2f3a4b5c
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveWebhookEvent'
responses:
'200':
description: Any 2xx acknowledges the delivery; the body is ignored.
servers:
- url: https://resolve.codai.ro
description: Production (private beta)
components:
schemas:
ResolveError:
type: object
title: Resolve error
description: 'Flat error envelope used by every Resolve endpoint. Not the gateway `{ error: { code, message } }` shape.'
required:
- error
properties:
error:
oneOf:
- type: string
description: Human-readable reason.
examples:
- invalid or missing API key
- not found
- $ref: '#/components/schemas/ResolveValidationDetails'
ResolveJob:
type: object
title: Job
description: Full job view returned by `GET /v1/resolve/jobs/{id}`. Nullable fields are `null` until the corresponding stage has run.
required:
- id
- status
- repo_url
- tier
- quote_micro_usd
- triage_reason
- decline_reason
- fail_reason
- cost_micro_usd
- attestation_id
- attestation_url
- created_at
- completed_at
properties:
id:
type: string
format: uuid
status:
$ref: '#/components/schemas/ResolveJobStatus'
repo_url:
type: string
format: uri
description: Normalised repository URL (trailing slash removed).
tier:
oneOf:
- $ref: '#/components/schemas/ResolveTier'
- type: 'null'
description: Quote tier; `null` until triage completes.
quote_micro_usd:
type:
- integer
- 'null'
description: Quoted price in USD micros; `null` until quoted, `0` on the free tier.
paid_with:
allOf:
- $ref: '#/components/schemas/ResolvePaidWith'
description: Present once the job was accepted (and recorded how it was paid).
triage_reason:
type:
- string
- 'null'
decline_reason:
type:
- string
- 'null'
description: Set only when `status` is `declined`.
fail_reason:
type:
- string
- 'null'
description: 'Set when `status` is `failed` or `error` (e.g. `dispatch failed: …`).'
cost_micro_usd:
type: integer
description: Upstream inference spend attributed to this job, USD micros. Informational — you are billed the quote, not the cost.
attestation_id:
type:
- string
- 'null'
format: uuid
description: Present once the job is `resolved`.
attestation_url:
type:
- string
- 'null'
description: Relative path `/v1/resolve/attestations/{attestation_id}`; `null` until resolved.
examples:
- /v1/resolve/attestations/1f2c1a3e-8d4b-4f8e-9a1b-0c2d3e4f5a6b
created_at:
type: string
format: date-time
completed_at:
type:
- string
- 'null'
format: date-time
issue_url:
type:
- string
- 'null'
format: uri
description: The GitHub issue URL given at intake; `null` when the issue was sent as text.
issue_title:
type:
- string
- 'null'
description: First line of the issue text (at most 120 characters); `null` when unknown.
ResolvePaidWith:
type: string
title: Payment method
description: 'How an accepted job is paid: `free` (free tier), `intro` (first paid job, €1 hold),
`credit` (one t7 fix credit, no wallet hold) or `wallet` (hold of the list price).
Precedence: `free` > `intro` > `credit` > `wallet`.
'
enum:
- intro
- credit
- wallet
- free
ResolveJobList:
type: object
title: Job page
description: One page of `GET /v1/resolve/jobs`.
required:
- jobs
- next_cursor
properties:
jobs:
type: array
items:
$ref: '#/components/schemas/ResolveJob'
next_cursor:
type:
- string
- 'null'
description: Pass as `cursor` to read the next page; `null` on the last page.
ResolveInsufficientFunds:
type: object
title: Insufficient funds
description: '`402` body of `POST /v1/resolve/jobs/{id}/accept` when the wallet cannot hold the quote.'
required:
- error
- balance
- required
- currency
- topup_url
properties:
error:
type: string
const: insufficient_funds
balance:
type: integer
description: Current wallet balance in EUR micros (`5000000` = €5.00).
examples:
- 5000000
required:
type: integer
description: Amount the hold needs in EUR micros — the quote converted 1:1 (`19000000` = €19).
examples:
- 19000000
currency:
type: string
const: micro_eur
description: Unit of `balance` and `required`.
topup_url:
type: string
format: uri
description: Wallet top-up checkout for the shortfall in whole euros, clamped to 10–1000.
examples:
- https://pay.codai.ro/checkout?topup=14
bundle_url:
type: string
format: uri
description: Present only for a `t7` job — checkout for the fix bundle (10 t7 fix credits for €49).
examples:
- https://pay.codai.ro/checkout?bundle=resolve10
ResolveWebhookEventName:
type: string
title: Webhook event
description: '`job.quoted` (paid quote ready), `job.declined` (triage refused), `job.resolved` (verified fix + attestation), `job.failed` (no verified fix, hold refunded), `job.error` (infrastructure failure, hold refunded).'
enum:
- job.quoted
- job.declined
- job.resolved
- job.failed
- job.error
ResolveBalance:
type: object
title: Balance
description: Body of `GET /v1/resolve/balance`.
required:
- fix_credits
- intro_available
- wallet_micro_eur
properties:
fix_credits:
type: integer
description: Fix credits left (usable only on `t7` jobs). Buy 10 for €49 at https://pay.codai.ro/checkout?bundle=resolve10.
examples:
- 10
intro_available:
type: boolean
description: '`true` while your next paid accept would hold the €1 intro price.'
wallet_micro_eur:
type: integer
description: Wallet balance in EUR micros (`5000000` = €5.00).
examples:
- 5000000
ResolveDeclined:
type: object
title: Declined
description: '`200` body — triage declined the issue. The job is persisted with `status: declined` and is never billed.'
required:
- id
- status
- decline_reason
properties:
id:
type: string
format: uuid
status:
type: string
const: declined
decline_reason:
type: string
examples:
- feature request, no testable behavior
- triage unavailable, please retry
callback_secret:
type: string
description: 'Present only when the intake carried `callback_url` (a `job.declined` event is sent
too). HMAC-SHA256 key for webhook signatures. **Returned once** — store it now.
'
examples:
- whsec_3q2-7wQ1d0X9mZk4Vb8yTnR5sLpA6cEe
ResolveWebhookJob:
type: object
title: Webhook job snapshot
description: Snapshot of the job at send time. Nullable fields are `null` until the corresponding stage has run.
required:
- id
- status
- tier
- quote_micro_usd
- repo_url
- decline_reason
- fail_reason
- cost_micro_usd
- attestation_id
- attestation_url
- completed_at
properties:
id:
type: string
format: uuid
status:
$ref: '#/components/schemas/ResolveJobStatus'
tier:
oneOf:
- $ref: '#/components/schemas/ResolveTier'
- type: 'null'
quote_micro_usd:
type:
- integer
- 'null'
description: Quoted price in USD micros; `0` on the free tier.
repo_url:
type: string
format: uri
decline_reason:
type:
- string
- 'null'
fail_reason:
type:
- string
- 'null'
cost_micro_usd:
type: integer
description: Upstream inference spend attributed to this job, USD micros (informational).
attestation_id:
type:
- string
- 'null'
format: uuid
attestation_url:
type:
- string
- 'null'
format: uri
description: Absolute URL of the public attestation (unlike the relative path on `GET /v1/resolve/jobs/{id}`).
examples:
- https://resolve.codai.ro/v1/resolve/attestations/1f2c1a3e-8d4b-4f8e-9a1b-0c2d3e4f5a6b
completed_at:
type:
- string
- 'null'
format: date-time
ResolveWebhookEvent:
type: object
title: Webhook event payload
description: JSON body POSTed to `callback_url`. Verify `x-codai-signature` over the raw bytes before trusting it.
required:
- event
- job
- sent_at
properties:
event:
$ref: '#/components/schemas/ResolveWebhookEventName'
job:
$ref: '#/components/schemas/ResolveWebhookJob'
sent_at:
type: string
format: date-time
description: When this delivery attempt was built (UTC).
ResolveTier:
type: string
title: Quote tier
description: '`free` (first 3 resolves per user), `t7` ($7), `t19` ($19), `t49` ($49). Prices are in USD micros on the wire.'
enum:
- free
- t7
- t19
- t49
ResolveJobStatus:
type: string
title: Job status
description: 'Lifecycle: `triage → quoted → accepted → running → resolved | failed`, plus `declined`
(triage refused) and `error` (infrastructure failure — retryable, never billed).
'
enum:
- triage
- quoted
- declined
- accepted
- running
- resolved
- failed
- error
ResolveValidationDetails:
type: object
title: Validation details
description: Zod `flatten()` output returned when the intake body fails schema validation.
required:
- formErrors
- fieldErrors
properties:
formErrors:
type: array
description: Errors on the whole object, e.g. `one of issue_url or issue_text is required`.
items:
type: string
fieldErrors:
type: object
description: Per-field error messages keyed by field name.
additionalProperties:
type: array
items:
type: string
ResolveIntake:
type: object
title: Resolve intake
description: Body of `POST /v1/resolve/jobs`. Provide `issue_url` or `issue_text` (at least one).
required:
- repo_url
properties:
repo_url:
type: string
format: uri
description: Public GitHub repository, `https://github.com/owner/repo` (optional `.git` or trailing slash). Anything else is rejected with `400`.
examples:
- https://github.com/psf/requests
issue_url:
type: string
format: uri
description: Public GitHub issue URL `https://github.com/owner/repo/issues/123`. Fetched without a token; ignored when `issue_text` is present.
examples:
- https://github.com/psf/requests/issues/6000
issue_text:
type: string
minLength: 10
maxLength: 50000
description: Inline issue description. Takes precedence over `issue_url`. Only the first 20 000 characters reach triage.
test_command:
type: string
maxLength: 2000
description: Optional FAIL_TO_PASS command (must fail before the fix and pass after). When omitted the agent writes a repro test first and includes it in the attestation.
examples:
- python -m pytest -q tests/test_x.py::test_y
callback_url:
type: string
format: uri
maxLength: 2000
description: 'Optional webhook target. Must be `https`, carry no credentials and point at a public
host (no localhost, private, link-local or metadata addresses; every DNS answer is
re-checked at delivery). Events are signed with the per-job `callback_secret`
returned in the intake response. Redirects are not followed.
'
examples:
- https://ci.example.com/hooks/codai-resolve
ResolveAccepted:
type: object
title: Accepted
required:
- id
- status
- paid_with
- held_micro_eur
properties:
id:
type: string
format: uuid
status:
type: string
const: accepted
paid_with:
$ref: '#/components/schemas/ResolvePaidWith'
held_micro_eur:
type: integer
minimum: 0
description: Amount held on the wallet in EUR micros — `1000000` for the intro, the quote for `wallet`, `0` for `credit`.
examples:
- 1000000
ResolveQuote:
type: object
title: Quote
description: '`201` body — the job was quoted (`quoted`) or auto-accepted on the free tier (`accepted`).'
required:
- id
- status
- tier
- quote_micro_usd
- triage_reason
- free_tier_remaining
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- quoted
- accepted
description: '`accepted` only when the free tier was used (already dispatched).'
tier:
$ref: '#/components/schemas/ResolveTier'
quote_micro_usd:
type: integer
description: Quoted price in USD micros (`7000000` = $7). `0` on the free tier.
examples:
- 7000000
triage_reason:
type: string
description: One-line triage rationale shown with the quote.
free_tier_remaining:
type: integer
minimum: 0
description: Free resolves left for this user after this submission.
intro_price_micro_eur:
type: integer
description: 'Present only on a `quoted` job while the intro price applies to you: accepting holds
this amount (EUR micros, `1000000` = €1) instead of the list price.
'
examples:
- 1000000
list_price_micro_eur:
type: integer
description: Present together with `intro_price_micro_eur`; the regular hold in EUR micros (the quote 1:1).
examples:
- 7000000
callback_secret:
type: string
description: 'Present only when the intake carried `callback_url`. HMAC-SHA256 key for verifying
webhook signatures. **Returned once** — it is never shown again, store it now.
'
examples:
- whsec_3q2-7wQ1d0X9mZk4Vb8yTnR5sLpA6cEe
responses:
ResolveInternalError:
description: The job row could not be inserted (`job insert failed`).
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveError'
ResolveConflict:
description: The job is not in the `quoted` state (`job is <status>, only quoted jobs can be accepted`).
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveError'
ResolveInsufficientFunds:
description: 'The wallet balance does not cover the quote. Nothing was debited and the job is still
`quoted`. Open `topup_url` (pay.codai.ro checkout, shortfall rounded up to whole euros,
minimum €10, maximum €1000) — or, for a `t7` job, `bundle_url` (10 fix credits for €49) —
then retry `/accept`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveInsufficientFunds'
ResolveNotFound:
description: No such job/attestation, or the job belongs to another user.
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveError'
ResolveUnauthorized:
description: Missing, malformed or revoked API key (`invalid or missing API key`).
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveError'
ResolveRateLimited:
description: 'One of the per-user abuse limits tripped: more than 6 submissions in a minute, 2 jobs
already in flight, or 10 jobs created today (UTC). No `Retry-After` header is sent; the
message says whether to wait a minute, for a job to finish, or until tomorrow.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveError'
ResolveBadRequest:
description: 'Invalid intake. `error` is a Zod `flatten()` object for schema failures (missing
`repo_url`, neither `issue_url` nor `issue_text`, text too short/long), or a string for
semantic failures (non-github.com repo URL, issue could not be fetched, fetched issue
has no usable text).
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveError'
parameters:
JobId:
name: id
in: path
required: true
description: Job UUID returned by `POST /v1/resolve/jobs`.
schema:
type: string
format: uuid
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: codai_…
description: An existing codai API key. Jobs are scoped to the key's user; all keys of one user share the same limits and free tier.
x-refined-from:
- codai-ro-resolve-openapi.json
- codai-ro-resolve-openapi.yml