{"openapi":"3.1.0","info":{"title":"Forge JSON API","version":"1.0.0","description":"Public API for managing documents and running utilities and pipelines."},"servers":[{"url":"/","description":"Current deployment"}],"tags":[{"name":"Documents"},{"name":"Utilities"},{"name":"Pipelines"},{"name":"AI Draft","description":"Generate a pipeline draft from a natural-language intent and sample JSON input."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Use `Authorization: Bearer fje_...`"}},"parameters":{"DocumentId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Document identifier"},"PipelineId":{"name":"pipelineId","in":"path","required":true,"schema":{"type":"string"},"description":"Pipeline identifier"},"UtilityId":{"name":"utilityId","in":"path","required":true,"schema":{"type":"string"},"description":"Utility identifier"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"code":{"type":"string"}},"required":["success","error"],"additionalProperties":false},"Document":{"type":"object","required":["id","name","title","tags","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"folderId":{"type":"string"},"fileSize":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}},"additionalProperties":false},"DocumentListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["success","documents","nextCursor"],"additionalProperties":false},"DocumentResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"document":{"$ref":"#/components/schemas/Document"}},"required":["success","document"],"additionalProperties":false},"DocumentCreateRequest":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"folder":{"anyOf":[{"type":"string"},{"type":"null"}]},"content":{}},"required":["name","content"],"additionalProperties":false},"DocumentUpdateRequest":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"folder":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"DocumentContentUpdateRequest":{"description":"Any valid JSON value to store as the document body."},"DocumentContentUpdateResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"fileSize":{"type":"number"}},"required":["success","fileSize"],"additionalProperties":false},"DeleteDocumentResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"deleted":{"type":"boolean","enum":[true]},"purgeAt":{"type":"number"}},"required":["success","deleted","purgeAt"],"additionalProperties":false},"PurgeDocumentResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"deleted":{"type":"boolean","enum":[true]},"permanent":{"type":"boolean","enum":[true]}},"required":["success","deleted","permanent"],"additionalProperties":false},"UtilityRunRequest":{"type":"object","properties":{"inputs":{"type":"object","description":"Named utility inputs. inputs.primary is always required. Multi-input utilities such as deep merge also require inputs.secondary.","properties":{"primary":{"description":"The primary JSON input for the utility."},"secondary":{"description":"Optional secondary JSON input. Required by multi-input utilities such as deep merge."}},"required":["primary"],"additionalProperties":true},"config":{"type":"object","additionalProperties":true}},"required":["inputs"],"additionalProperties":false},"UtilityRunResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"output":{},"durationMs":{"type":"number"},"creditsUsed":{"type":"number"}},"required":["success","output","durationMs","creditsUsed"],"additionalProperties":false},"PipelineRunRequest":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":true},"verbose":{"type":"boolean"}},"additionalProperties":false},"PipelineRunResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"status":{"type":"string","enum":["completed","completed_with_warnings","skipped","failed"]},"output":{},"durationMs":{"type":"number"},"creditsUsed":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","additionalProperties":true}},"stepOutputs":{"type":"object","additionalProperties":true}},"required":["success","status","output","durationMs","creditsUsed"],"additionalProperties":false},"AIDraftErrorItem":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code. Callers should branch on this value rather than parsing `message`.","enum":["UNAUTHORIZED","FORBIDDEN","INVALID_JSON","INVALID_MODEL","INVALID_CONFIG","EMPTY_DRAFT","UNKNOWN_UTILITY","SEMANTIC_MISMATCH","STEP_LIMIT_EXCEEDED","INPUT_TOO_LARGE","MODEL_FAILURE","TIMEOUT","RATE_LIMITED","DAILY_QUOTA_EXCEEDED","PLATFORM_AT_CAPACITY","LIMITER_UNAVAILABLE","USER_KEY_BROKEN","AI_DRAFT_BYO_REQUIRED"]},"message":{"type":"string"},"stepIndex":{"type":"number"},"utilityId":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"AIDraftErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"errors":{"type":"array","items":{"$ref":"#/components/schemas/AIDraftErrorItem"}}},"required":["success","errors"],"additionalProperties":false},"AIDraftRequest":{"type":"object","properties":{"intent":{"type":"string","description":"Natural-language description of the transformation (for example, \"Convert this CSV-like JSON array to a clean list of user records with trimmed names\")."},"sampleInput":{"type":"string","description":"A sample JSON input as a string. Maximum 200,000 bytes. The draft is shaped around this sample."},"model":{"type":"string","description":"Optional provider-specific model identifier (e.g. `gpt-4o-mini`). When omitted the account default is used."}},"required":["intent","sampleInput"],"additionalProperties":false},"AIDraftStep":{"type":"object","properties":{"utilityId":{"type":"string","description":"Identifier of a utility available in the Store."},"config":{"type":"object","description":"Config object for the utility. Shape is utility-specific.","additionalProperties":true}},"required":["utilityId","config"],"additionalProperties":false},"AIDraftPlan":{"type":"object","properties":{"steps":{"type":"array","items":{"$ref":"#/components/schemas/AIDraftStep"}},"explanation":{"type":"string"}},"required":["steps"],"additionalProperties":false},"AIDraftResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"draft":{"$ref":"#/components/schemas/AIDraftPlan"},"pipeline":{"type":"object","description":"Full pipeline graph (nodes + edges) ready to import via the pipeline builder or run via `POST /api/v1/pipelines/{pipelineId}/run` after saving.","additionalProperties":true},"explanation":{"type":"string"},"remaining":{"type":"number","description":"Daily AI Draft requests remaining for this caller after this call."},"nearingLimit":{"type":"boolean","description":"True when remaining / daily cap drops below 20%."}},"required":["success","draft","pipeline"],"additionalProperties":false}},"examples":{"Document":{"summary":"Document metadata","value":{"id":"jx73rbeegn51rvay2qjjpjfssh83f379","name":"customer-records","title":"customer-records","description":"Imported customer records","tags":["crm","import"],"folderId":"k97p0g6c8h9m1n2b3v4x5z6a7s8d9f0q","fileSize":2048,"createdAt":1774283979968,"updatedAt":1774283982042}}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/documents":{"get":{"operationId":"listDocuments","tags":["Documents"],"summary":"List documents","description":"Lists documents visible to the authenticated API key. Supports folder filtering and cursor pagination.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum number of documents to return."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor returned by a previous list response."},{"name":"folder","in":"query","schema":{"type":"string"},"description":"Folder path filter, for example `codex-e2e/reports`."}],"responses":{"200":{"description":"Document list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"},"example":{"success":true,"documents":[{"id":"jx73rbeegn51rvay2qjjpjfssh83f379","name":"customer-records","title":"customer-records","description":"Imported customer records","tags":["crm","import"],"folderId":"k97p0g6c8h9m1n2b3v4x5z6a7s8d9f0q","fileSize":2048,"createdAt":1774283979968,"updatedAt":1774283982042}],"nextCursor":"jx78y1btc85h4mkq10ms9kgs4x83f5f7"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Query parameter 'limit' must be a positive integer","code":"INVALID_LIMIT"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"createDocument","tags":["Documents"],"summary":"Create a document","description":"Document upload limits are plan-based: Starter 5MB, Pro 10MB, Team 20MB. Requests above the current plan limit return 413.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreateRequest"},"example":{"name":"customer-records","description":"Imported customer records","tags":["crm","import"],"folder":"imports/2026","content":{"customers":[{"id":1,"email":"ada@example.com"}]}}}}},"responses":{"201":{"description":"Document created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"},"example":{"success":true,"document":{"id":"jx73rbeegn51rvay2qjjpjfssh83f379","name":"customer-records","title":"customer-records","description":"Imported customer records","tags":["crm","import"],"folderId":"k97p0g6c8h9m1n2b3v4x5z6a7s8d9f0q","fileSize":2048,"createdAt":1774283979968,"updatedAt":1774283982042}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Invalid JSON in request body","code":"INVALID_JSON"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"413":{"description":"Payload too large for the current document plan limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/documents/{id}":{"get":{"operationId":"getDocument","tags":["Documents"],"summary":"Get document metadata","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Document metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"},"example":{"success":true,"document":{"id":"jx73rbeegn51rvay2qjjpjfssh83f379","name":"customer-records","title":"customer-records","description":"Imported customer records","tags":["crm","import"],"folderId":"k97p0g6c8h9m1n2b3v4x5z6a7s8d9f0q","fileSize":2048,"createdAt":1774283979968,"updatedAt":1774283982042}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Document not found"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateDocument","tags":["Documents"],"summary":"Update document metadata","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateRequest"},"example":{"name":"customer-records-updated","description":"Reviewed and normalized","tags":["crm","reviewed"],"folder":"imports/reviewed"}}}},"responses":{"200":{"description":"Updated document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"},"example":{"success":true,"document":{"id":"jx73rbeegn51rvay2qjjpjfssh83f379","name":"customer-records-updated","title":"customer-records-updated","description":"Reviewed and normalized","tags":["crm","reviewed"],"folderId":"k97p0g6c8h9m1n2b3v4x5z6a7s8d9f0q","fileSize":2048,"createdAt":1774283979968,"updatedAt":1774284982042}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"No fields to update","code":"NO_UPDATES"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Document not found"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteDocument","tags":["Documents"],"summary":"Soft-delete a document","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Document soft-deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteDocumentResponse"},"example":{"success":true,"deleted":true,"purgeAt":1776875982042}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Document not found"}}}},"429":{"description":"Too many delete requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Too many delete requests. Try again later."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/documents/{id}/content":{"get":{"operationId":"getDocumentContent","tags":["Documents"],"summary":"Download document content","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Document content","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Document not found"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"operationId":"updateDocumentContent","tags":["Documents"],"summary":"Replace document content","description":"Document upload limits are plan-based: Starter 5MB, Pro 10MB, Team 20MB. Requests above the current plan limit return 413.","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentContentUpdateRequest"},"example":{"customers":[{"id":1,"email":"ada@example.com"}]}}}},"responses":{"200":{"description":"Document content updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentContentUpdateResponse"},"example":{"success":true,"fileSize":2048}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Invalid JSON in request body","code":"INVALID_JSON"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Document not found"}}}},"413":{"description":"Payload too large for the current document plan limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/documents/{id}/purge":{"post":{"operationId":"purgeDocument","tags":["Documents"],"summary":"Permanently delete a soft-deleted document","parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Document permanently deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeDocumentResponse"},"example":{"success":true,"deleted":true,"permanent":true}}}},"400":{"description":"Document must be soft-deleted first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing documents permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'documents' permission"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Document not found"}}}},"429":{"description":"Too many purge requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Too many purge requests. Try again later."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/utilities/{utilityId}":{"post":{"operationId":"runUtility","tags":["Utilities"],"summary":"Run a utility","parameters":[{"$ref":"#/components/parameters/UtilityId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtilityRunRequest"},"example":{"inputs":{"primary":{"customer_name":"  Ada Lovelace  "}},"config":{"trimWhitespace":true}}}}},"responses":{"200":{"description":"Utility output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UtilityRunResponse"},"example":{"success":true,"output":{"customer_name":"Ada Lovelace"},"durationMs":12,"creditsUsed":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Invalid JSON in request body","code":"INVALID_JSON"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing utilities permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'utilities' permission"}}}},"404":{"description":"Utility not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Utility not found","code":"UTILITY_NOT_FOUND"}}}},"408":{"description":"Execution timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/ai/pipeline-draft":{"post":{"operationId":"generateAIPipelineDraft","tags":["AI Draft"],"summary":"Generate an AI pipeline draft","description":"Generates a pipeline draft from a natural-language intent and a sample JSON input. Returns both the validated draft (as `steps[]`) and a full pipeline graph (`nodes` + `edges`) ready for import or execution. Requires a bound AI provider credential on the API key (BYO).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftRequest"},"example":{"intent":"Clean each customer record: trim the name, lowercase the email, and drop null fields.","sampleInput":"[{\"name\":\"  Ada  \",\"email\":\"ADA@EXAMPLE.COM\",\"note\":null}]","model":"gpt-4o-mini"}}}},"responses":{"200":{"description":"Draft generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftResponse"},"example":{"success":true,"draft":{"steps":[{"utilityId":"cleanup.format-values","config":{"targets":["name"],"operation":"trim"}},{"utilityId":"cleanup.format-values","config":{"targets":["email"],"operation":"lowercase"}},{"utilityId":"schema.clean-json","config":{"removeNulls":true}}],"explanation":"Trim the name, lowercase the email, then drop fields with null values."},"pipeline":{"nodes":[],"edges":[]},"explanation":"Trim the name, lowercase the email, then drop fields with null values.","remaining":47,"nearingLimit":false}}}},"400":{"description":"Invalid request or draft validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"INVALID_CONFIG","message":"Intent is required."}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"UNAUTHORIZED","message":"Invalid API key"}]}}}},"403":{"description":"Missing permission or BYO credential required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"AI_DRAFT_BYO_REQUIRED","message":"AI Draft API requires a saved default AI provider credential for this account."}]}}}},"408":{"description":"AI provider timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"TIMEOUT","message":"The AI provider took too long to respond."}]}}}},"413":{"description":"Sample input exceeds 200,000 bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"INPUT_TOO_LARGE","message":"Sample input is too large for AI drafting."}]}}}},"429":{"description":"Rate limited or daily quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"RATE_LIMITED","message":"You're going a bit fast. Try again in a moment."}]}}}},"500":{"description":"Unexpected model failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"MODEL_FAILURE","message":"Failed to generate AI pipeline draft."}]}}}},"502":{"description":"AI provider call failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"MODEL_FAILURE","message":"Failed to generate AI pipeline draft."}]}}}},"503":{"description":"AI Draft disabled or at capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIDraftErrorResponse"},"example":{"success":false,"errors":[{"code":"PLATFORM_AT_CAPACITY","message":"AI Draft is temporarily at capacity. Try again later."}]}}}}}}},"/api/v1/pipelines/{pipelineId}/run":{"post":{"operationId":"runPipeline","tags":["Pipelines"],"summary":"Run a pipeline","parameters":[{"$ref":"#/components/parameters/PipelineId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineRunRequest"},"example":{"inputs":{"default":{"customer_name":"Ada Lovelace"}},"verbose":true}}}},"responses":{"200":{"description":"Pipeline output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineRunResponse"},"example":{"success":true,"output":{"greeting":"Hello Ada Lovelace"},"durationMs":46,"creditsUsed":1,"stepOutputs":{"input_1":{"customer_name":"Ada Lovelace"},"format_name":{"greeting":"Hello Ada Lovelace"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Pipeline produced no output","code":"PIPELINE_NO_OUTPUT"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing pipelines permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"API key does not have 'pipelines' permission"}}}},"404":{"description":"Pipeline not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Pipeline not found"}}}},"408":{"description":"Execution timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded. Try again later.","code":"RATE_LIMITED"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}