{ "openapi": "3.1.0", "info": { "title": "FirstHandAPI", "version": "1.0.0", "description": "Crowdsourced content collection API. Post jobs requesting files, workers upload content, AI scores quality, approved files auto-deliver to your folder.", "contact": { "url": "https://firsthandapi.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.firsthandapi.com", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local development" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v1/jobs": { "post": { "operationId": "createJob", "summary": "Post a job requesting file-based content", "tags": [ "Jobs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "description", "files_needed", "accepted_formats", "price_per_file_cents" ], "properties": { "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "minLength": 10, "maxLength": 5000, "type": "string" }, "files_needed": { "minimum": 1, "maximum": 10000, "type": "integer" }, "accepted_formats": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "minimum": 1, "maximum": 100000, "type": "integer" }, "metadata": { "maxProperties": 50, "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for idempotent job creation" } ], "responses": { "201": { "description": "Job created, credits escrowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "organization_id", "type", "description", "files_needed", "files_approved", "files_remaining", "accepted_formats", "price_per_file_cents", "platform_fee_pct", "total_cost_cents", "worker_payout_per_file_cents", "status", "metadata", "created_at", "completed_at", "cancelled_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job", "type": "string" }, "organization_id": { "type": "string" }, "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "type": "string" }, "files_needed": { "type": "integer" }, "files_approved": { "type": "integer" }, "files_remaining": { "type": "integer" }, "accepted_formats": { "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "type": "integer" }, "platform_fee_pct": { "type": "number" }, "total_cost_cents": { "type": "integer" }, "worker_payout_per_file_cents": { "type": "integer" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "in_progress", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "created_at": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } }, "get": { "operationId": "listJobs", "summary": "List jobs", "tags": [ "Jobs" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Job list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "organization_id", "type", "description", "files_needed", "files_approved", "files_remaining", "accepted_formats", "price_per_file_cents", "platform_fee_pct", "total_cost_cents", "worker_payout_per_file_cents", "status", "metadata", "created_at", "completed_at", "cancelled_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job", "type": "string" }, "organization_id": { "type": "string" }, "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "type": "string" }, "files_needed": { "type": "integer" }, "files_approved": { "type": "integer" }, "files_remaining": { "type": "integer" }, "accepted_formats": { "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "type": "integer" }, "platform_fee_pct": { "type": "number" }, "total_cost_cents": { "type": "integer" }, "worker_payout_per_file_cents": { "type": "integer" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "in_progress", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "created_at": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJob", "summary": "Get job by ID", "description": "Supports long-polling via `Prefer: wait=N` header (max 60s). Server holds connection until job completes or timeout.", "tags": [ "Jobs" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Long-poll: \"wait=30\" holds connection up to 30s until job completes", "example": "wait=30" } ], "responses": { "200": { "description": "Job details", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "organization_id", "type", "description", "files_needed", "files_approved", "files_remaining", "accepted_formats", "price_per_file_cents", "platform_fee_pct", "total_cost_cents", "worker_payout_per_file_cents", "status", "metadata", "created_at", "completed_at", "cancelled_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job", "type": "string" }, "organization_id": { "type": "string" }, "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "type": "string" }, "files_needed": { "type": "integer" }, "files_approved": { "type": "integer" }, "files_remaining": { "type": "integer" }, "accepted_formats": { "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "type": "integer" }, "platform_fee_pct": { "type": "number" }, "total_cost_cents": { "type": "integer" }, "worker_payout_per_file_cents": { "type": "integer" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "in_progress", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "created_at": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/jobs/{job_id}/cancel": { "post": { "operationId": "cancelJob", "summary": "Cancel a job and refund remaining credits", "tags": [ "Jobs" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job cancelled, remaining credits refunded", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "organization_id", "type", "description", "files_needed", "files_approved", "files_remaining", "accepted_formats", "price_per_file_cents", "platform_fee_pct", "total_cost_cents", "worker_payout_per_file_cents", "status", "metadata", "created_at", "completed_at", "cancelled_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job", "type": "string" }, "organization_id": { "type": "string" }, "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "type": "string" }, "files_needed": { "type": "integer" }, "files_approved": { "type": "integer" }, "files_remaining": { "type": "integer" }, "accepted_formats": { "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "type": "integer" }, "platform_fee_pct": { "type": "number" }, "total_cost_cents": { "type": "integer" }, "worker_payout_per_file_cents": { "type": "integer" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "in_progress", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "created_at": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "409": { "description": "Job cannot be cancelled in current state", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/jobs/{job_id}/files": { "get": { "operationId": "getJobFiles", "summary": "List approved files for a job with download URLs", "description": "Returns all approved files with pre-signed download URLs (7-day expiry).", "tags": [ "Jobs" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Approved files", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "job_id", "submission_id", "content_type", "size_bytes", "duration_seconds", "width", "height", "original_filename", "download_url", "download_url_expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "file", "type": "string" }, "job_id": { "type": "string" }, "submission_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_url": { "type": "string" }, "download_url_expires_at": { "type": "string" }, "created_at": { "type": "string" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/jobs/{job_id}/submissions": { "get": { "operationId": "getJobSubmissions", "summary": "List submissions for a job", "tags": [ "Jobs" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Submission list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "job_id", "status", "ai_star_rating", "ai_reasoning", "file", "created_at", "scored_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "submission", "type": "string" }, "job_id": { "type": "string" }, "status": { "anyOf": [ { "const": "pending_score", "type": "string" }, { "const": "approved", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "retry_pending", "type": "string" } ] }, "ai_star_rating": { "anyOf": [ { "minimum": 1, "maximum": 5, "type": "integer" }, { "type": "null" } ] }, "ai_reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file": { "anyOf": [ { "type": "object", "required": [ "id", "object", "job_id", "submission_id", "content_type", "size_bytes", "duration_seconds", "width", "height", "original_filename", "download_url", "download_url_expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "file", "type": "string" }, "job_id": { "type": "string" }, "submission_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_url": { "type": "string" }, "download_url_expires_at": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "created_at": { "type": "string" }, "scored_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/api_keys": { "post": { "operationId": "createApiKey", "summary": "Create a new API key", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "scopes", "environment" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "scopes": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "expires_at": { "type": "string" } } } } } }, "responses": { "201": { "description": "API key created (secret revealed once)", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "name", "prefix", "secret", "scopes", "environment", "status", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "api_key", "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "secret": { "type": "string" }, "scopes": { "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "rotating", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } }, "get": { "operationId": "listApiKeys", "summary": "List API keys (secrets masked)", "tags": [ "API Keys" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "API key list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "name", "prefix", "hint", "scopes", "environment", "status", "last_used_at", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "api_key", "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "hint": { "type": "string" }, "scopes": { "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "rotating", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/api_keys/{key_id}/rotate": { "post": { "operationId": "rotateApiKey", "summary": "Rotate an API key (24h overlap window)", "tags": [ "API Keys" ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotated key", "content": { "application/json": { "schema": { "type": "object", "required": [ "new_key", "old_key_expires_at" ], "properties": { "new_key": { "type": "object", "required": [ "id", "object", "name", "prefix", "secret", "scopes", "environment", "status", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "api_key", "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "secret": { "type": "string" }, "scopes": { "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "rotating", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "old_key_expires_at": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Key not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/api_keys/{key_id}/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke an API key immediately", "tags": [ "API Keys" ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Key revoked" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Key not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/webhook_endpoints": { "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "format": "uri", "type": "string" }, "description": { "maxLength": 500, "type": "string" } } } } } }, "responses": { "201": { "description": "Webhook endpoint created (signing_secret revealed once)", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "url", "status", "description", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint", "type": "string" }, "url": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Webhook endpoint list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "url", "status", "description", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint", "type": "string" }, "url": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/webhook_endpoints/{endpoint_id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get webhook endpoint by ID", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoint", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "url", "status", "description", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint", "type": "string" }, "url": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "format": "uri", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] } } } } } }, "responses": { "200": { "description": "Updated webhook endpoint", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "url", "status", "description", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint", "type": "string" }, "url": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Endpoint deleted" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/webhook_endpoints/{endpoint_id}/rotate_secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate webhook signing secret", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotated secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "new_secret", "old_secret_invalidates_at" ], "properties": { "new_secret": { "type": "string" }, "old_secret_invalidates_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Endpoint not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/webhook_events": { "get": { "operationId": "listWebhookEvents", "summary": "List webhook events", "tags": [ "Webhooks" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } }, { "name": "event_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook event list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "type", "endpoint_id", "status", "attempt_count", "data", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "event", "type": "string" }, "type": { "type": "string" }, "endpoint_id": { "type": "string" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "failed", "type": "string" } ] }, "attempt_count": { "type": "integer" }, "data": {}, "created_at": { "type": "string" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/webhook_events/{event_id}/replay": { "post": { "operationId": "replayWebhookEvent", "summary": "Replay a webhook event", "tags": [ "Webhooks" ], "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Event queued for replay", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "type", "endpoint_id", "status", "attempt_count", "data", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "event", "type": "string" }, "type": { "type": "string" }, "endpoint_id": { "type": "string" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "failed", "type": "string" } ] }, "attempt_count": { "type": "integer" }, "data": {}, "created_at": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Event not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/billing/credits": { "get": { "operationId": "getCreditBalance", "summary": "Get current credit balance", "tags": [ "Billing" ], "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance_cents", "currency", "updated_at" ], "properties": { "balance_cents": { "type": "integer" }, "currency": { "const": "usd", "type": "string" }, "updated_at": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/billing/transactions": { "get": { "operationId": "listTransactions", "summary": "List credit transactions", "tags": [ "Billing" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction list", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "properties": { "object": { "const": "list", "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "type", "description", "amount_cents", "running_balance_cents", "job_id", "expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "credit_transaction", "type": "string" }, "type": { "anyOf": [ { "const": "purchase", "type": "string" }, { "const": "deduction", "type": "string" }, { "const": "free_tier", "type": "string" }, { "const": "bonus", "type": "string" }, { "const": "expiration", "type": "string" }, { "const": "refund", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount_cents": { "type": "integer" }, "running_balance_cents": { "type": "integer" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/billing/credits/purchase": { "post": { "operationId": "purchaseCredits", "summary": "Initiate credit purchase via Stripe Checkout", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_cents" ], "properties": { "amount_cents": { "anyOf": [ { "const": 1000, "type": "number" }, { "const": 2500, "type": "number" }, { "const": 5000, "type": "number" }, { "const": 10000, "type": "number" }, { "const": 25000, "type": "number" } ] } } } } } }, "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "type": "object", "required": [ "checkout_url", "session_id" ], "properties": { "checkout_url": { "type": "string" }, "session_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } }, "/v1/organization/settings": { "get": { "operationId": "getOrganizationSettings", "summary": "Get organization settings", "tags": [ "Organization" ], "responses": { "200": { "description": "Organization settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_platform_fee_pct": { "type": [ "number", "null" ] }, "auto_top_up_enabled": { "type": "boolean" }, "auto_top_up_threshold_cents": { "type": [ "integer", "null" ] }, "auto_top_up_amount_cents": { "type": [ "integer", "null" ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } }, "patch": { "operationId": "updateOrganizationSettings", "summary": "Update organization settings", "tags": [ "Organization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_platform_fee_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 0.5 }, "auto_top_up_enabled": { "type": "boolean" }, "auto_top_up_threshold_cents": { "type": [ "integer", "null" ], "minimum": 0 }, "auto_top_up_amount_cents": { "type": [ "integer", "null" ], "minimum": 100 } } } } } }, "responses": { "200": { "description": "Updated organization settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_platform_fee_pct": { "type": [ "number", "null" ] }, "auto_top_up_enabled": { "type": "boolean" }, "auto_top_up_threshold_cents": { "type": [ "integer", "null" ] }, "auto_top_up_amount_cents": { "type": [ "integer", "null" ] } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (fh_live_* or fh_test_*) as Bearer token" } }, "schemas": { "CreateJobRequest": { "type": "object", "required": [ "type", "description", "files_needed", "accepted_formats", "price_per_file_cents" ], "properties": { "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "minLength": 10, "maxLength": 5000, "type": "string" }, "files_needed": { "minimum": 1, "maximum": 10000, "type": "integer" }, "accepted_formats": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "minimum": 1, "maximum": 100000, "type": "integer" }, "metadata": { "maxProperties": 50, "type": "object", "patternProperties": { "^(.*)$": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } } }, "JobResponse": { "type": "object", "required": [ "id", "object", "organization_id", "type", "description", "files_needed", "files_approved", "files_remaining", "accepted_formats", "price_per_file_cents", "platform_fee_pct", "total_cost_cents", "worker_payout_per_file_cents", "status", "metadata", "created_at", "completed_at", "cancelled_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "job", "type": "string" }, "organization_id": { "type": "string" }, "type": { "anyOf": [ { "const": "data_collection", "type": "string" }, { "const": "feedback", "type": "string" } ] }, "description": { "type": "string" }, "files_needed": { "type": "integer" }, "files_approved": { "type": "integer" }, "files_remaining": { "type": "integer" }, "accepted_formats": { "type": "array", "items": { "anyOf": [ { "const": "image/png", "type": "string" }, { "const": "image/jpeg", "type": "string" }, { "const": "image/webp", "type": "string" }, { "const": "audio/mpeg", "type": "string" }, { "const": "audio/wav", "type": "string" }, { "const": "audio/mp4", "type": "string" }, { "const": "video/mp4", "type": "string" }, { "const": "video/quicktime", "type": "string" } ] } }, "price_per_file_cents": { "type": "integer" }, "platform_fee_pct": { "type": "number" }, "total_cost_cents": { "type": "integer" }, "worker_payout_per_file_cents": { "type": "integer" }, "status": { "anyOf": [ { "const": "open", "type": "string" }, { "const": "in_progress", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "metadata": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "created_at": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "FileResponse": { "type": "object", "required": [ "id", "object", "job_id", "submission_id", "content_type", "size_bytes", "duration_seconds", "width", "height", "original_filename", "download_url", "download_url_expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "file", "type": "string" }, "job_id": { "type": "string" }, "submission_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_url": { "type": "string" }, "download_url_expires_at": { "type": "string" }, "created_at": { "type": "string" } } }, "SubmissionResponse": { "type": "object", "required": [ "id", "object", "job_id", "status", "ai_star_rating", "ai_reasoning", "file", "created_at", "scored_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "submission", "type": "string" }, "job_id": { "type": "string" }, "status": { "anyOf": [ { "const": "pending_score", "type": "string" }, { "const": "approved", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "retry_pending", "type": "string" } ] }, "ai_star_rating": { "anyOf": [ { "minimum": 1, "maximum": 5, "type": "integer" }, { "type": "null" } ] }, "ai_reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file": { "anyOf": [ { "type": "object", "required": [ "id", "object", "job_id", "submission_id", "content_type", "size_bytes", "duration_seconds", "width", "height", "original_filename", "download_url", "download_url_expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "file", "type": "string" }, "job_id": { "type": "string" }, "submission_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "duration_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "original_filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_url": { "type": "string" }, "download_url_expires_at": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "created_at": { "type": "string" }, "scored_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name", "scopes", "environment" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "scopes": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "expires_at": { "type": "string" } } }, "CreateApiKeyResponse": { "type": "object", "required": [ "id", "object", "name", "prefix", "secret", "scopes", "environment", "status", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "api_key", "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "secret": { "type": "string" }, "scopes": { "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "rotating", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "ApiKeyListItem": { "type": "object", "required": [ "id", "object", "name", "prefix", "hint", "scopes", "environment", "status", "last_used_at", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "api_key", "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "hint": { "type": "string" }, "scopes": { "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "rotating", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "RotateApiKeyResponse": { "type": "object", "required": [ "new_key", "old_key_expires_at" ], "properties": { "new_key": { "type": "object", "required": [ "id", "object", "name", "prefix", "secret", "scopes", "environment", "status", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "api_key", "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "secret": { "type": "string" }, "scopes": { "type": "array", "items": { "anyOf": [ { "const": "jobs:write", "type": "string" }, { "const": "jobs:read", "type": "string" }, { "const": "webhooks:write", "type": "string" }, { "const": "webhooks:read", "type": "string" }, { "const": "keys:manage", "type": "string" }, { "const": "audit:read", "type": "string" }, { "const": "usage:read", "type": "string" }, { "const": "billing:write", "type": "string" } ] } }, "environment": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "test", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "rotating", "type": "string" }, { "const": "revoked", "type": "string" } ] }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "old_key_expires_at": { "type": "string" } } }, "CreateWebhookEndpointRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "format": "uri", "type": "string" }, "description": { "maxLength": 500, "type": "string" } } }, "WebhookEndpointResponse": { "type": "object", "required": [ "id", "object", "url", "status", "description", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint", "type": "string" }, "url": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "signing_secret": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "UpdateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "format": "uri", "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "disabled", "type": "string" } ] } } }, "RotateWebhookSecretResponse": { "type": "object", "required": [ "new_secret", "old_secret_invalidates_at" ], "properties": { "new_secret": { "type": "string" }, "old_secret_invalidates_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "WebhookEventResponse": { "type": "object", "required": [ "id", "object", "type", "endpoint_id", "status", "attempt_count", "data", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "event", "type": "string" }, "type": { "type": "string" }, "endpoint_id": { "type": "string" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "delivered", "type": "string" }, { "const": "failed", "type": "string" } ] }, "attempt_count": { "type": "integer" }, "data": {}, "created_at": { "type": "string" } } }, "CreditBalanceResponse": { "type": "object", "required": [ "balance_cents", "currency", "updated_at" ], "properties": { "balance_cents": { "type": "integer" }, "currency": { "const": "usd", "type": "string" }, "updated_at": { "type": "string" } } }, "CreditTransaction": { "type": "object", "required": [ "id", "object", "type", "description", "amount_cents", "running_balance_cents", "job_id", "expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "credit_transaction", "type": "string" }, "type": { "anyOf": [ { "const": "purchase", "type": "string" }, { "const": "deduction", "type": "string" }, { "const": "free_tier", "type": "string" }, { "const": "bonus", "type": "string" }, { "const": "expiration", "type": "string" }, { "const": "refund", "type": "string" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount_cents": { "type": "integer" }, "running_balance_cents": { "type": "integer" }, "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string" } } }, "PurchaseCreditsRequest": { "type": "object", "required": [ "amount_cents" ], "properties": { "amount_cents": { "anyOf": [ { "const": 1000, "type": "number" }, { "const": 2500, "type": "number" }, { "const": 5000, "type": "number" }, { "const": 10000, "type": "number" }, { "const": 25000, "type": "number" } ] } } }, "PurchaseCreditsResponse": { "type": "object", "required": [ "checkout_url", "session_id" ], "properties": { "checkout_url": { "type": "string" }, "session_id": { "type": "string" } } }, "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "message", "request_id" ], "properties": { "type": { "anyOf": [ { "const": "invalid_request", "type": "string" }, { "const": "authentication_error", "type": "string" }, { "const": "authorization_error", "type": "string" }, { "const": "not_found", "type": "string" }, { "const": "conflict", "type": "string" }, { "const": "rate_limit_exceeded", "type": "string" }, { "const": "validation_error", "type": "string" }, { "const": "insufficient_credits", "type": "string" }, { "const": "internal_error", "type": "string" } ] }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } } } } }