{ "note": "All examples use {API_BASE_URL} as a placeholder for the server base URL.", "examples": [ { "id": "register_key", "title": "Register an API key", "request": { "method": "POST", "path": "{API_BASE_URL}/v1/keys/register", "headers": { "Content-Type": "application/json" }, "body": { "email": "agent@example.com" } }, "response": { "status": 201, "body": { "apiKey": "ol_live_01J...", "accountId": "key_01J..." } } }, { "id": "create_output_multipart", "title": "Upload a PDF via multipart/form-data", "request": { "method": "POST", "path": "{API_BASE_URL}/v1/outputs", "headers": { "Authorization": "Bearer ol_live_01J...", "Content-Type": "multipart/form-data", "Idempotency-Key": "report-2024-q4-v1" }, "fields": { "mimeType": "application/pdf", "label": "Q4 Report.pdf", "public": "false", "metadata": "{\"agentId\":\"agent-123\",\"jobId\":\"job-456\"}" }, "file_field": "content" }, "response": { "status": 201, "body": { "outputId": "out_01J...", "status": "ready", "label": "Q4 Report.pdf", "mimeType": "application/pdf", "sizeBytes": 204800, "createdAt": "2024-11-01T10:00:00.000Z", "expiresAt": "2024-11-08T10:00:00.000Z", "publicUrl": null, "contentUrl": "{API_BASE_URL}/v1/outputs/out_01J.../content", "metadata": { "agentId": "agent-123", "jobId": "job-456" }, "agent_contract": { "version": "1", "content_accessible": true, "safe_to_share": false, "retryable": false, "expires_in_seconds": 604800, "next_actions": [ { "action": "download_content", "available": true, "recommended": true, "method": "GET", "endpoint": "{API_BASE_URL}/v1/outputs/out_01J.../content" } ] } } } }, { "id": "create_output_json", "title": "Upload JSON content via application/json", "request": { "method": "POST", "path": "{API_BASE_URL}/v1/outputs", "headers": { "Authorization": "Bearer ol_live_01J...", "Content-Type": "application/json", "Idempotency-Key": "analysis-result-v1" }, "body": { "mimeType": "application/json", "content": "eyJyZXN1bHQiOiAib2sifQ==", "label": "analysis.json", "public": true } }, "response": { "status": 201, "body": { "outputId": "out_01J...", "status": "ready", "label": "analysis.json", "mimeType": "application/json", "sizeBytes": 16, "publicUrl": "https://cdn.outputlayer.dev/out_01J...", "contentUrl": "{API_BASE_URL}/v1/outputs/out_01J.../content", "metadata": {}, "agent_contract": { "version": "1", "content_accessible": true, "safe_to_share": true, "retryable": false, "next_actions": [ { "action": "share_public_url", "available": true, "recommended": true, "method": "GET", "endpoint": "https://cdn.outputlayer.dev/out_01J..." } ] } } } }, { "id": "get_output", "title": "Get output metadata (ready)", "request": { "method": "GET", "path": "{API_BASE_URL}/v1/outputs/out_01J...", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 200, "body": { "outputId": "out_01J...", "status": "ready", "label": "Q4 Report.pdf", "mimeType": "application/pdf", "sizeBytes": 204800, "createdAt": "2024-11-01T10:00:00.000Z", "expiresAt": "2024-11-08T10:00:00.000Z", "publicUrl": null, "contentUrl": "{API_BASE_URL}/v1/outputs/out_01J.../content", "metadata": {}, "agent_contract": { "version": "1", "content_accessible": true, "safe_to_share": false, "retryable": false, "expires_in_seconds": 604800, "next_actions": [ { "action": "download_content", "available": true, "recommended": true, "description": "Download the raw content via the authenticated content endpoint.", "method": "GET", "endpoint": "/v1/outputs/out_01J.../content" }, { "action": "create_public_output", "available": false, "recommended": false, "reason": "This output was created without public:true.", "required_body_changes": { "public": true } }, { "action": "delete_output", "available": true, "recommended": false, "description": "Delete this output when it is no longer needed.", "method": "DELETE", "endpoint": "/v1/outputs/out_01J..." } ] } } } }, { "id": "get_output_failed", "title": "Get output metadata (failed upload)", "note": "A failed upload returns HTTP 200 with status:\"failed\". contentUrl and publicUrl are null because the content was never stored. The agent should retry the identical upload request with the same Idempotency-Key.", "request": { "method": "GET", "path": "{API_BASE_URL}/v1/outputs/out_01J...", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 200, "body": { "outputId": "out_01J...", "status": "failed", "label": "Q4 Report.pdf", "mimeType": "application/pdf", "sizeBytes": 0, "createdAt": "2024-11-01T10:00:00.000Z", "expiresAt": "2024-11-08T10:00:00.000Z", "publicUrl": null, "contentUrl": null, "metadata": {}, "agent_contract": { "version": "1", "content_accessible": false, "safe_to_share": false, "retryable": true, "expires_in_seconds": 604800, "next_actions": [ { "action": "retry_same_request", "available": true, "recommended": true, "description": "Retry the identical request with the same Idempotency-Key.", "method": "POST", "endpoint": "/v1/outputs" } ] } } } }, { "id": "get_content_expired", "title": "Stream content — output expired (HTTP 410)", "note": "GET /v1/outputs/:id/content returns a JSON error body (not raw bytes) when the output status is expired or deleted.", "request": { "method": "GET", "path": "{API_BASE_URL}/v1/outputs/out_01J.../content", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 410, "body": { "error": "output_expired", "message": "This output has expired and its content is no longer available.", "request_id": "req_01J...", "agent_contract": { "version": "1", "content_accessible": false, "safe_to_share": false, "retryable": false, "expires_in_seconds": null, "next_actions": [ { "action": "create_new_output", "available": true, "recommended": true, "description": "The content for this output has expired. Upload again to create a new output.", "method": "POST", "endpoint": "/v1/outputs" } ] } } } }, { "id": "get_content_failed", "title": "Stream content — upload failed (HTTP 422)", "note": "GET /v1/outputs/:id/content returns HTTP 422 with a JSON error body when the upload for this output did not complete successfully. Retry the original POST /v1/outputs with the same Idempotency-Key.", "request": { "method": "GET", "path": "{API_BASE_URL}/v1/outputs/out_01J.../content", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 422, "body": { "error": "upload_failed", "message": "The content for this output was not successfully uploaded. Retry with the same Idempotency-Key.", "request_id": "req_01J...", "agent_contract": { "version": "1", "content_accessible": false, "safe_to_share": false, "retryable": true, "expires_in_seconds": null, "next_actions": [ { "action": "retry_same_request", "available": true, "recommended": true, "description": "Retry the identical request with the same Idempotency-Key.", "method": "POST", "endpoint": "/v1/outputs" } ] } } } }, { "id": "get_content", "title": "Stream raw file content (authenticated)", "note": "Authenticated private retrieval mode. Requires API key. Content-Disposition uses the label supplied at creation. Use publicUrl (CDN mode) to share without authentication when public: true was set.", "request": { "method": "GET", "path": "{API_BASE_URL}/v1/outputs/out_01J.../content", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 200, "headers": { "Content-Type": "application/pdf", "Content-Disposition": "attachment; filename=\"Q4 Report.pdf\"", "Cache-Control": "private, no-store" }, "body": "" } }, { "id": "get_output_expired", "title": "Get metadata for an expired output (HTTP 410)", "note": "Expired and deleted outputs return HTTP 410 with the full output object shape — not a bare error envelope. contentUrl and publicUrl are null.", "request": { "method": "GET", "path": "{API_BASE_URL}/v1/outputs/out_01J...", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 410, "body": { "outputId": "out_01J...", "status": "expired", "label": "Q4 Report.pdf", "mimeType": "application/pdf", "sizeBytes": 204800, "createdAt": "2024-11-01T10:00:00.000Z", "expiresAt": "2024-11-08T10:00:00.000Z", "publicUrl": null, "contentUrl": null, "metadata": { "agentId": "agent-123", "jobId": "job-456" }, "agent_contract": { "version": "1", "content_accessible": false, "safe_to_share": false, "retryable": false, "expires_in_seconds": null, "next_actions": [ { "action": "create_new_output", "available": true, "recommended": true, "description": "The content for this output has expired. Upload again to create a new output.", "method": "POST", "endpoint": "/v1/outputs" } ] } } } }, { "id": "delete_output", "title": "Delete an output", "request": { "method": "DELETE", "path": "{API_BASE_URL}/v1/outputs/out_01J...", "headers": { "Authorization": "Bearer ol_live_01J..." } }, "response": { "status": 200, "body": { "outputId": "out_01J...", "status": "deleted", "deletedAt": "2024-11-01T12:00:00.000Z", "agent_contract": { "version": "1", "content_accessible": false, "safe_to_share": false, "retryable": false, "expires_in_seconds": null, "next_actions": [ { "action": "create_new_output", "available": true, "recommended": true, "method": "POST", "endpoint": "/v1/outputs" } ] } } } }, { "id": "idempotency_replay", "title": "Replay a successful upload (same Idempotency-Key)", "request": { "method": "POST", "path": "{API_BASE_URL}/v1/outputs", "headers": { "Authorization": "Bearer ol_live_01J...", "Idempotency-Key": "report-2024-q4-v1", "Content-Type": "multipart/form-data" }, "note": "Same Idempotency-Key as a prior successful request." }, "response": { "status": 201, "note": "Returns the cached response from the original successful upload." } }, { "id": "idempotency_in_flight", "title": "Upload rejected — same key already being processed", "note": "Two requests arrive concurrently with the same Idempotency-Key. The first claims the slot and proceeds normally. The second receives HTTP 503 with a Retry-After: 5 header. Retry the identical request (same key + same payload) after 5 seconds.", "request": { "method": "POST", "path": "{API_BASE_URL}/v1/outputs", "headers": { "Authorization": "Bearer ol_live_01J...", "Idempotency-Key": "report-2024-q4-v1", "Content-Type": "multipart/form-data" }, "note": "A concurrent request with this same Idempotency-Key is already being processed." }, "response": { "status": 503, "headers": { "Retry-After": "5" }, "body": { "error": "idempotency_in_flight", "message": "A request with this Idempotency-Key is already being processed. Retry with the same key and payload after 5 seconds.", "agent_contract": { "version": "1", "content_accessible": false, "safe_to_share": false, "retryable": true, "expires_in_seconds": null, "next_actions": [ { "action": "retry_after_wait", "available": true, "recommended": true, "description": "A request with this Idempotency-Key is already being processed. Wait and retry with the same key and payload.", "method": "POST", "endpoint": "/v1/outputs", "retry_after_seconds": 5 } ] } } } }, { "id": "quota_exhausted", "title": "Upload rejected — no quota remaining", "response": { "status": 402, "body": { "error": "quota_exhausted", "message": "No free quota or credits remaining. Purchase credits to continue.", "agent_contract": { "version": "1", "content_accessible": false, "retryable": false, "next_actions": [ { "action": "buy_credits", "available": true, "recommended": true, "method": "POST", "endpoint": "/v1/credits/checkout" }, { "action": "check_capabilities", "available": true, "recommended": false, "method": "GET", "endpoint": "/v1/capabilities" } ] } } } } ], "supported_mime_types": [ "application/json", "application/octet-stream", "application/pdf", "application/xml", "application/zip", "image/gif", "image/jpeg", "image/png", "image/webp", "text/csv", "text/html", "text/plain" ] }