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

  1. Create or open a project from the Dashboard
  2. Click "Generate New API Key"
  3. 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

POST /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
  • booleantrue/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 key
  • 403 — API key not authorized for this project
  • 404 — Task not found
  • 400 — Invalid inputs or missing required fields
  • 503 — 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 key
  • INVALID_API_KEY / invalid_api_key — Invalid or expired key
  • FORBIDDEN / forbidden — Key not authorized for project
  • NOT_FOUND / not_found — Task or variant not found
  • VALIDATION_ERROR / validation_error — Invalid or missing inputs
  • SERVICE_UNAVAILABLE / service_unavailable — LLM provider not configured
  • INTERNAL_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: true in metadata
  • Handle network errors gracefully
  • Implement retry logic with backoff