A
Atlas
...

Projects API

Manage projects programmatically. Projects are containers for forms.

List Projects

http
GET /api/v1/projects

Returns all projects for the authenticated account. Works with an account token (atl_...) or a project API key (fep_...). See Authentication.

Example Request

bash
curl "https://atlasforms.app/api/v1/projects" \
  -H "Authorization: Bearer fep_your_api_key"

Response

json
{
  "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

http
GET /api/v1/projects/{id}

Returns a single project with its forms.

Example Request

bash
curl "https://atlasforms.app/api/v1/projects/project-uuid" \
  -H "Authorization: Bearer fep_your_api_key"

Response

json
{
  "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

http
PATCH /api/v1/projects/{id}

Updates a project. Requires a project API key (fep_...) belonging to the same account. Send any of these fields:

FieldDescription
nameProject name
webhook_urlDefault webhook URL, or null to remove it
allowed_originsArray of allowed domains
is_activefalse to stop accepting submissions
bash
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

http
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.

json
{ "success": true, "deleted_id": "project-uuid" }

Create Project

http
POST /api/v1/projects

Creates a new project with a default "Contact Form".

Request Body

json
{
  "name": "My New Project",
  "webhook_url": "https://example.com/webhook",
  "allowed_origins": ["example.com"]
}
FieldRequiredDescription
nameYesProject name
webhook_urlNoDefault webhook URL for the project's forms
allowed_originsNoArray 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

bash
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

json
{
  "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

http
GET /api/v1/projects/{id}/forms

Returns all forms in a project.

Example Request

bash
curl "https://atlasforms.app/api/v1/projects/project-uuid/forms" \
  -H "Authorization: Bearer fep_your_api_key"

Response

json
{
  "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

http
POST /api/v1/projects/{id}/forms

Creates a new form in a project.

Request Body

json
{
  "name": "Newsletter Signup",
  "slug": "newsletter",
  "webhook_url": "https://example.com/newsletter-hook",
  "success_redirect": "https://example.com/subscribed",
  "allowed_origins": ["example.com"]
}
FieldRequiredDescription
nameYesForm name
slugNoURL-friendly slug, unique within the project. Derived from the name if omitted.
webhook_urlNoWebhook URL for this form
success_redirectNoURL to redirect to after a browser submission
allowed_originsNoArray of domains allowed to submit to this form. Defaults to the project's allowed origins.
ai_spam_filterNotrue 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

bash
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

json
{
  "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

http
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.

FieldDescription
nameForm name (non-empty)
webhook_urlhttp(s) URL, or null to remove
success_redirecthttp(s) URL, or null to remove
allowed_originsArray of domains (full URLs are stored as hostnames), or null to use the project's
ai_spam_filtertrue 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

bash
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

json
{
  "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

json
{ "error": "Invalid API key" }

403 Forbidden

Plan limit reached. Don't retry; upgrade the plan or remove unused projects or forms.

json
{ "error": "You've reached the maximum of 1 projects on the Starter plan" }

404 Not Found

json
{ "error": "Project not found" }

429 Rate Limited

json
{ "error": "Rate limit exceeded" }