Developer API / docs
API reference
Every endpoint, in the order you meet them: catalog, jobs, files, webhooks, account. Machine-readable version: openapi.yaml.
Base URL and auth
https://api.gigai.tools/v1
Authorization: Bearer gk_live_...Scopes live on keys. New keys carry jobs:read, jobs:write, tools:run and webhooks:manage. gk_test_ keys are sandbox: nothing counts against quota.
Tools
GET/v1/tools
List every runnable engine with its options schema.
Auth: none
Jobs
POST/v1/jobs
Create a job from a graph of named tasks.
Auth: jobs:write
Idempotency-Key(header) - Same key returns the same job instead of re-running. Up to 200 chars.
Body
tasks(object, required) - Task name to task. Operations: import/url, import/base64, any tool slug, export/url.tag(string) - Your own label, up to 128 chars, echoed back.retention_s(integer) - 0..86400, default 3600. Zero means one download or 60 seconds.
Errors: invalid_request, invalid_option, file_too_large, concurrent_limit, quota_exceeded, rate_limited
GET/v1/jobs
Recent jobs, newest first. ?status= and ?limit= (max 50).
Auth: jobs:read
GET/v1/jobs/{id}/wait
Long-poll: answers when the job settles or after ~55 s.
Auth: jobs:read
Errors: not_found
DELETE/v1/jobs/{id}
Cancel outstanding work and delete every file immediately, verified.
Auth: jobs:write
Errors: not_found
Files
DELETE/v1/files/{id}
Delete now, without waiting for retention. Answer confirms verification.
Auth: jobs:write
Errors: not_found
GET/v1/files/{id}/download
The signed download itself - no auth header, the signature is the auth.
Auth: none
e(integer, required) - Expiry, unix epoch.s(string, required) - HMAC signature.
Errors: bad_signature, not_found
Webhooks
POST/v1/webhooks
Register an https endpoint. The signing secret is in the answer exactly once.
Auth: webhooks:manage
Body
url(string, required) - https only, must resolve to a public address.events(string[]) - Subset of job.finished, job.failed. Default: both.
Errors: invalid_request, webhook_limit
GET/v1/webhooks
List endpoints. Secrets never included.
Auth: webhooks:manage
Account & auth
POST/v1/auth/signup
Create an account. Sends a verification email.
Auth: none
Body
email(string, required) - A real inbox - the verify link goes there.password(string, required) - At least 10 characters.
Errors: email_taken, invalid_email, weak_password
POST/v1/auth/login
Exchange credentials for a 12-hour dashboard session token.
Auth: none
Errors: bad_credentials, email_unverified, account_suspended
GET/v1/account
Plan, limits and this month's usage. Session auth.
Auth: dashboard session
POST/v1/keys
Create an API key. The secret appears once. Session auth.
Auth: dashboard session
Errors: too_many_keys
Agent planning
POST/v1/agent/plan
Goal sentence + file metadata in, a tool pipeline out - planned by a free-tier model chain and meant to be validated against the live catalog before running. Strictly text-only: file contents are never accepted. 10 plans/day per account.
Auth: API key
Body
goal(string, required) - What should happen, one sentence, up to 500 chars.files(array) - Up to 10 entries of {name, type, size, width?, height?} - metadata only.catalogue(array) - Optional tool list to plan against (the MCP server sends its own). Defaults to the server engine catalog.
Errors: invalid_request, agent_quota, planning_unavailable
POST/v1/agent/learn
Store one opt-in learning record: goal, plan, step outcomes, whether the plan was edited. Never file names, contents or results; records are metadata-sized and refused otherwise. The answer echoes exactly what was stored.
Auth: API key
Body
opt_in(boolean, required) - Must be literally true - there is no implicit consent.goal(string, required) - The goal sentence.plan(object, required) - The plan that ran, {steps: [...]}.outcomes(array, required) - Per step: {toolId, ok, corrected}.edited(boolean) - Whether the user changed the proposed plan before running.
Errors: invalid_request