API Reference
The Forge API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Base URL
All API requests should be made to the following base URL:
https://api.useforge.cloud/v1Authentication
The Forge API uses API keys to authenticate requests. You can view and manage your API keys in theDashboard Settings.
Security Notice: Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.
Authorization: Basic <BASE64_ENCODED_API_KEY>Alternatively, you may use Bearer Token authentication:
Authorization: Bearer sk_live_1234567890Request Format
POST requests should use application/json as the Content-Type. Arguments can be passed as query parameters for GET requests.
Idempotency: For POST requests that mutate data, we recommend sending an Idempotency-Key header. This allows you to safely retry requests without performing the same operation twice.
Response Format
All responses are strictly JSON. The top-level object will always contain the resource or a list of resources.
{
"object": "submission",
"id": "sub_12345",
"created_at": 1678900000,
"data": { ... }
}Errors
Forge uses conventional HTTP response codes to indicate the success or failure of an API request.
| Code | Description |
|---|---|
| 200 - OK | Everything worked as expected. |
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | No valid API key provided. |
| 403 - Forbidden | The API key doesn't have permissions to perform the request. |
| 404 - Not Found | The requested resource doesn't exist. |
| 429 - Too Many Requests | Too many requests hit the API too quickly. |
| 500 - Server Error | Something went wrong on Forge's end. |
Error Response Body:
{
"error": {
"code": "parameter_missing",
"message": "The 'email' parameter is required."
}
}Rate Limits
Our API uses a token bucket algorithm to enforce rate limits. Limits are applied per API key. Information regarding your current rate limit status is returned in the response headers.
- Header
- X-RateLimit-Limit
- The maximum number of requests you are permitted to make per minute.
- Header
- X-RateLimit-Remaining
- The number of requests remaining in the current time window.
If you exceed the limit, the API returns a 429 status. We recommend implementing an exponential backoff retry strategy.
Versioning
The API is versioned via the URL path. The current stable version is v1.
Changes that break backward compatibility (renaming fields, removing endpoints) will result in a new version number (e.g., v2). Additive changes (new fields, new optional parameters) may be introduced within v1 without notice.