Projects API
Manage projects programmatically. Projects are containers for forms.
List Projects
GET /api/v1/projectsReturns all projects for the authenticated account. Works with an account token (atl_...) or a project API key (fep_...). See Authentication.
Example Request
curl "https://atlasforms.app/api/v1/projects" \
-H "Authorization: Bearer fep_your_api_key"Response
{
"data": [
{
"id": "project-uuid",
"name": "My Website",
"slug": "my-website",
"api_key_prefix": "fep_abc12345",
"webhook_url": "https://example.com/webhook",
"allowed_origins": ["example.com", "www.example.com"],
"is_active": true,
"forms_count": 3,
"created_at": "2024-01-15T10:30:00Z"
}
]
}Get Project
GET /api/v1/projects/{id}Returns a single project with its forms.
Example Request
curl "https://atlasforms.app/api/v1/projects/project-uuid" \
-H "Authorization: Bearer fep_your_api_key"Response
{
"data": {
"id": "project-uuid",
"name": "My Website",
"slug": "my-website",
"api_key_prefix": "fep_abc12345",
"webhook_url": "https://example.com/webhook",
"allowed_origins": ["example.com"],
"is_active": true,
"created_at": "2024-01-15T10:30:00Z",
"forms": [
{
"id": "form-uuid",
"name": "Contact Form",
"slug": "contact",
"public_id": "abc123xyz",
"is_active": true,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}Update Project
PATCH /api/v1/projects/{id}Updates a project. Requires a project API key (fep_...) belonging to the same account. Send any of these fields:
| Field | Description |
|---|---|
name | Project name |
webhook_url | Default webhook URL, or null to remove it |
allowed_origins | Array of allowed domains |
is_active | false to stop accepting submissions |
curl -X PATCH "https://atlasforms.app/api/v1/projects/project-uuid" \
-H "Authorization: Bearer fep_your_api_key" \
-H "Content-Type: application/json" \
-d '{"allowed_origins": ["example.com"]}'The response contains the updated project in data.
Delete Project
DELETE /api/v1/projects/{id}Deletes the project with its forms, submissions, and uploaded files. Requires an account token (atl_...); project API keys get 403. This cannot be undone.
{ "success": true, "deleted_id": "project-uuid" }Create Project
POST /api/v1/projectsCreates a new project with a default "Contact Form".
Request Body
{
"name": "My New Project",
"webhook_url": "https://example.com/webhook",
"allowed_origins": ["example.com"]
}| Field | Required | Description |
|---|---|---|
name | Yes | Project name |
webhook_url | No | Default webhook URL for the project's forms |
allowed_origins | No | Array of domains allowed to submit, such as "example.com". Full URLs are accepted and stored as hostnames. Subdomains are included automatically. |
Set allowed_origins to the site's production domain. A form with no allowed domains rejects every submission from the live site. Localhost testing works without it (see sandbox mode).
Example Request
curl -X POST "https://atlasforms.app/api/v1/projects" \
-H "Authorization: Bearer atl_your_account_token" \
-H "Content-Type: application/json" \
-d '{"name": "My New Project", "allowed_origins": ["example.com"]}'CLI equivalent: atlas projects create "My New Project" --origin example.com --json
Response
201 Created
{
"data": {
"id": "new-project-uuid",
"name": "My New Project",
"slug": "project-lx2k9a",
"api_key_prefix": "fep_abc12345",
"webhook_url": null,
"allowed_origins": ["example.com"],
"is_active": true,
"created_at": "2024-01-25T10:30:00Z",
"api_key": "fep_...",
"default_form": {
"slug": "contact",
"public_id": "abc123xyz",
"endpoint": "https://atlasforms.app/f/abc123xyz"
}
}
}api_key is the project API key. It is returned only once, on creation. Forms don't need it; it is only for server-side API access, so keep it out of frontend code.
If the site has only a contact form, use default_form.endpoint and skip creating another form.
List Forms in Project
GET /api/v1/projects/{id}/formsReturns all forms in a project.
Example Request
curl "https://atlasforms.app/api/v1/projects/project-uuid/forms" \
-H "Authorization: Bearer fep_your_api_key"Response
{
"data": [
{
"id": "form-uuid",
"public_id": "abc123xyz",
"name": "Contact Form",
"slug": "contact",
"endpoint": "https://atlasforms.app/f/abc123xyz",
"webhook_url": null,
"success_redirect": "https://example.com/thank-you",
"is_active": true,
"validation_mode": "sandbox",
"ai_spam_filter": false,
"submissions_count": 500,
"created_at": "2024-01-15T10:30:00Z"
}
]
}Create Form
POST /api/v1/projects/{id}/formsCreates a new form in a project.
Request Body
{
"name": "Newsletter Signup",
"slug": "newsletter",
"webhook_url": "https://example.com/newsletter-hook",
"success_redirect": "https://example.com/subscribed",
"allowed_origins": ["example.com"]
}| Field | Required | Description |
|---|---|---|
name | Yes | Form name |
slug | No | URL-friendly slug, unique within the project. Derived from the name if omitted. |
webhook_url | No | Webhook URL for this form |
success_redirect | No | URL to redirect to after a browser submission |
allowed_origins | No | Array of domains allowed to submit to this form. Defaults to the project's allowed origins. |
ai_spam_filter | No | true to turn on the AI spam filter. Default false. When on, submission text is sent to Cloudflare Workers AI for classification. Free on every plan. |
New forms start in sandbox mode.
Example Request
curl -X POST "https://atlasforms.app/api/v1/projects/project-uuid/forms" \
-H "Authorization: Bearer atl_your_account_token" \
-H "Content-Type: application/json" \
-d '{"name": "Newsletter Signup"}'CLI equivalent: atlas forms create "Newsletter Signup" --project project-uuid --json
Response
201 Created
{
"data": {
"id": "new-form-uuid",
"name": "Newsletter Signup",
"slug": "newsletter-signup",
"public_id": "xyz789abc",
"webhook_url": null,
"allowed_origins": null,
"success_redirect": null,
"is_active": true,
"validation_mode": "sandbox",
"ai_spam_filter": false,
"created_at": "2024-01-25T10:30:00Z",
"endpoint": "https://atlasforms.app/f/xyz789abc"
}
}A 409 response means a form with that slug already exists in the project.
Update Form
PATCH /api/v1/forms/{id}Updates a form's settings. {id} is the form's id (the UUID from the forms list), not the public id in the endpoint URL. Requires an account token (atl_...); project API keys get 403. Only the fields you send change.
| Field | Description |
|---|---|
name | Form name (non-empty) |
webhook_url | http(s) URL, or null to remove |
success_redirect | http(s) URL, or null to remove |
allowed_origins | Array of domains (full URLs are stored as hostnames), or null to use the project's |
ai_spam_filter | true or false: the AI spam filter. When on, submission text is sent to Cloudflare Workers AI for classification. |
Any other field is rejected with 400 and a message naming it. A form that doesn't exist or isn't yours returns 404.
Example Request
curl -X PATCH "https://atlasforms.app/api/v1/forms/form-uuid" \
-H "Authorization: Bearer atl_your_account_token" \
-H "Content-Type: application/json" \
-d '{"ai_spam_filter": true}'CLI equivalent: atlas forms update form-uuid --spam-filter on --json
Response
{
"data": {
"id": "form-uuid",
"project_id": "project-uuid",
"name": "Contact Form",
"slug": "contact",
"public_id": "abc123xyz",
"endpoint": "https://atlasforms.app/f/abc123xyz",
"webhook_url": null,
"allowed_origins": null,
"success_redirect": null,
"is_active": true,
"validation_mode": "live",
"ai_spam_filter": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-20T09:00:00Z"
}
}Error Responses
401 Unauthorized
{ "error": "Invalid API key" }403 Forbidden
Plan limit reached. Don't retry; upgrade the plan or remove unused projects or forms.
{ "error": "You've reached the maximum of 1 projects on the Starter plan" }404 Not Found
{ "error": "Project not found" }429 Rate Limited
{ "error": "Rate limit exceeded" }