FARPY PUBLIC API V1

GPU Workload API for developers and agents.

Submit bounded GPU work, inspect canonical state, retrieve the artifact, and retain the receipt and proof. The live machine contract is authoritative.

Create API keyOpen quickstart
farpy-api.sh
$ curl -fsS https://farpy.com/v1/health
{"ok":true}

$ curl -fsS https://farpy.com/v1/capabilities \
  -H "Authorization: Bearer $FARPY_API_KEY"

$ python3 farpy_client.py render scene.blend
uploading
queued
running
complete
artifact downloaded
receipt verified
AUTHBearer API keys
RETRIESIdempotent submission
DELIVERYArtifact + receipt + proof
CONTRACTRuntime discovery

01 / DISCOVERY

Live service contract

Do not hard-code renderer availability, pricing, limits, or cancellation behavior.
GET /v1/healthService healthGET /v1/capabilitiesWorkload availabilityGET /v1/pricingCurrent pricingGET /v1/limitsCurrent limitsGET /v1/openapi.jsonOpenAPI 3.1

02 / CONTRACT

Current public contract

ACCEPT

Discover and validate

Inspect health, capabilities, pricing, limits, and the OpenAPI contract before submission.

EXECUTE

Upload and submit

Authenticate with a bearer key and use idempotency keys for deliberate retry behavior.

VERIFY

Download and prove

Completed work exposes artifact delivery, a receipt, and execution proof tied to canonical state.

03 / GUIDES

Integration guides

01API quickstartFirst authenticated render from health check to download.↗02Agent renderingMachine-operated submission, polling, webhooks, and verification.↗03Blender Render APIProgrammatic Blender Cycles upload-to-download workflow.↗04Webhook deliverySigned terminal events, retries, acknowledgement, and duplicates.↗

04 / MCP

Model Context Protocol (MCP)

Agents can discover and invoke the FARPY MCP server through a standard tool interface.
MCP SERVER

FARPY MCP server

Agents can discover and invoke FARPY's 10 MCP tools for verified compute workflows.

AUTH

FARPY_API_KEY

Authenticate MCP requests with the FARPY_API_KEY environment variable.

REFERENCE

Capabilities, pricing, limits

Use the live API references for supported capabilities, pricing rules, and workload limits.

04 / AUTH

Authentication and key management

  1. 1
    Sign inAPI keys are created and revoked from Account Settings.
  2. 2
    Copy onceThe farpy_… secret is displayed once after creation.
  3. 3
    Use bearer authAuthorization: Bearer farpy_<secret>
  4. 4
    Revoke immediatelyRevoked keys stop authenticating without delay.
REQUEST HEADER
Authorization: Bearer farpy_<secret>
CREATE KEY
POST /v1/api-keys
{"name":"production-agent"}
REVOKE KEY
DELETE /v1/api-keys/{key_id}

05 / CLIENT

Dependency-free Python client

Python 3 standard library. No SDK dependency chain.
farpy_client.pyfarpy_client_example.pySHA256SUMS
export FARPY_API_KEY="farpy_..."

python3 farpy_client.py render scene.blend

# individual operations
python3 farpy_client.py upload scene.blend
python3 farpy_client.py submit JOB_ID
python3 farpy_client.py status JOB_ID

06 / SUBMIT

Copy-paste workload submission

The API key remains in the environment and is not printed.
bashsubmit-render.sh
#!/usr/bin/env bash
set -euo pipefail

: "${FARPY_API_KEY:?Set FARPY_API_KEY first}"
: "${1:?Usage: ./submit-render.sh scene.blend}"

BASE="https://farpy.com/v1"
FILE="$1"
AUTH="Authorization: Bearer $FARPY_API_KEY"
UPLOAD_KEY="upload-$(sha256sum "$FILE" | awk '{print $1}')"
SUBMIT_KEY="submit-$UPLOAD_KEY"

curl -fsS "$BASE/health"
curl -fsS "$BASE/capabilities" -H "$AUTH"
curl -fsS "$BASE/pricing" -H "$AUTH"
curl -fsS "$BASE/limits" -H "$AUTH"

UPLOAD="$(
  curl -fsS "$BASE/uploads"     -H "$AUTH"     -H "Idempotency-Key: $UPLOAD_KEY"     -F "file=@$FILE"
)"

UPLOAD_ID="$(printf "%s" "$UPLOAD" | jq -r ".upload_id")"

curl -fsS "$BASE/renders"   -H "$AUTH"   -H "Content-Type: application/json"   -H "Idempotency-Key: $SUBMIT_KEY"   --data "$(jq -nc --arg upload_id "$UPLOAD_ID"     '{upload_id:$upload_id}')"

07 / RETRIES

Safe retries with idempotency

Send a stable Idempotency-Key for upload and render creation. A repeated request with the same key can resolve to the original operation instead of silently producing duplicate billable work.

UPLOAD
Idempotency-Key: upload-<input-sha256>
SUBMISSION
Idempotency-Key: submit-<request-id>
OPTIONAL FINGERPRINT
X-Farpy-Request-Fingerprint: <sha256>

08 / ROUTES

Verified routes

Paths are relative to https://farpy.com/v1.
GET/healthCheck service availability before sending credentials or work.
GET/capabilitiesRead currently accepted renderers, formats, queue state, and availability.
GET/pricingRead the active machine-readable pricing contract.
GET/limitsRead upload, frame, rate, and workload constraints.
GET/openapi.jsonDownload the OpenAPI 3.1 contract.
POST/uploadsUpload a supported workload file.
POST/rendersCreate an idempotent render job.
GET/renders/{job_id}Read canonical job state and progress.
POST/renders/{job_id}/cancelCancel before worker claim when the live contract permits it.
GET/renders/{job_id}/downloadRetrieve completed artifact delivery information.
GET/renders/{job_id}/receiptRetrieve the economic completion receipt.
GET/renders/{job_id}/proofRetrieve execution evidence and artifact hashes.

STATUS · RECEIPT · DOWNLOAD

The job is not complete until the artifact, receipt, and proof are retrievable.

System statusReceipt guideManage API keys