API Documentation
Programmatic access to execute tasks
Overview
The Forgeable API lets you execute tasks programmatically. Send inputs via multipart/form-data and receive streamed responses.
- Base URL:
https://forgeable.com/api/v1 - Authentication: Project API Key via Bearer token
- Input Format:
multipart/form-data - Output Format: Raw text stream with metadata
Getting Started
1. Generate an API Key
- Create or open a project from the Dashboard
- Click "Generate New API Key"
- Copy the key immediately (shown only once)
2. Make Your First Request
curl -X POST "https://forgeable.com/api/v1/projects/PROJECT_ID/tasks/my-task/execute" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "input_field=your value here"
Authentication
All API requests require a project API key passed via the Authorization header:
Authorization: Bearer YOUR_PROJECT_API_KEY
API keys are scoped to a specific project and can only execute tasks within that project.
Execute Task
/api/v1/projects/:projectId/tasks/:taskIdentifier/execute
Execute a task and stream the response. Uses multipart/form-data for inputs.
Endpoint Variants
| Endpoint | Format | Variant |
|---|---|---|
/execute |
Minimal (raw text) | Active variant |
/execute/variant/:variantId |
Minimal (raw text) | Specific variant |
/execute/openai |
OpenAI SSE | Active variant |
/execute/openai/variant/:variantId |
OpenAI SSE | Specific variant |
Input Types
- text — String value
- number — Numeric value
- boolean —
true/false - select — One of predefined options
- file — File upload (images, PDF, text)
Response Format
Raw text content streamed in real-time, followed by \x1e\n separator and JSON metadata:
The streamed output content here...\x1e
{"execution_id":"uuid","tokens_input":150,"tokens_output":42,"duration_ms":1234}
Streaming Example
curl -N -X POST "https://forgeable.com/api/v1/projects/PROJECT_ID/tasks/my-task/execute" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "input_field=your value here"
File Upload
curl -N -X POST "https://forgeable.com/api/v1/projects/PROJECT_ID/tasks/my-task/execute" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "document=@report.pdf" \
-F "query=Summarize this document"
Errors
401— Invalid or missing API key403— API key not authorized for this project404— Task not found400— Invalid inputs or missing required fields503— LLM provider not configured
Errors also use the \x1e\n separator format with "error": true in the metadata.
OpenAI-Compatible Format
Use /execute/openai for OpenAI-style SSE streaming. To target a specific variant, use /execute/openai/variant/:variantId.
curl -N -X POST "https://forgeable.com/api/v1/projects/PROJECT_ID/tasks/my-task/execute/openai" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "input_field=your value here"
Response Format
data: {"id":"exec_abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"exec_abc","object":"chat.completion.chunk","choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]
Error Handling
Error format depends on which endpoint you use:
Minimal Format /execute
Uses the \x1e\n separator format with error details in metadata:
\x1e
{"error":true,"code":"INVALID_API_KEY","message":"Invalid, expired, or revoked API key"}
OpenAI Format /execute/openai
Returns errors in OpenAI-compatible JSON structure:
{
"error": {
"message": "Invalid, expired, or revoked API key",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}
Error Types (OpenAI Format)
authentication_error— 401 responses (invalid/missing API key)permission_error— 403 responses (key not authorized)not_found_error— 404 responses (task/variant not found)invalid_request_error— 400 responses (validation errors)service_unavailable_error— 503 responses (LLM not configured)server_error— 500 responses (internal errors)
Error Codes
UNAUTHORIZED/unauthorized— Missing API keyINVALID_API_KEY/invalid_api_key— Invalid or expired keyFORBIDDEN/forbidden— Key not authorized for projectNOT_FOUND/not_found— Task or variant not foundVALIDATION_ERROR/validation_error— Invalid or missing inputsSERVICE_UNAVAILABLE/service_unavailable— LLM provider not configuredINTERNAL_ERROR/internal_error— Server error
Best Practices
Security
- Never commit API keys to version control
- Use environment variables
- Rotate keys regularly
- Revoke compromised keys immediately
Error Handling
- Always check for
error: truein metadata - Handle network errors gracefully
- Implement retry logic with backoff