Grawt API Documentation

Overview

The Grawt API allows you to programmatically manage pages, discover domains, and manage leads, tags, and custom fields in your Grawt account. This RESTful API uses JSON for request and response bodies.

Base URL: https://grawt.app/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header.

Example:

curl -H "X-API-Key: your-api-key" https://grawt.app/api/v1/leads/fields

Error Responses

Leads

Add Lead

Creates a new lead in your account.

Endpoint: POST /api/v1/leads

Request Body:

Example Request:

{
  "email": "john@example.com",
  "fields": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  }
}

Success Response (201):

{
  "success": true,
  "message": "Lead added successfully."
}

Update Lead

Updates an existing lead by email address.

Endpoint: PUT /api/v1/leads/{email}

URL Parameters:

Request Body:

Example Request:

{
  "fields": {
    "first_name": "Jonathan",
    "phone": "+1987654321"
  }
}

Success Response (200):

{
  "success": true,
  "message": "Lead successfully updated."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Sync Lead

Creates a new lead or updates an existing one based on the email address. This is useful for upsert operations where you want to ensure the lead exists with the latest data.

Endpoint: POST /api/v1/leads/sync

Request Body:

Example Request:

{
  "email": "john@example.com",
  "fields": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  },
  "add_tags": [1, 5, 12],
  "remove_tags": [3]
}

Success Response (200):

{
  "success": true,
  "message": "Lead successfully created."
}

or

{
  "success": true,
  "message": "Lead successfully updated."
}

Delete Lead

Permanently deletes a lead by email address.

Endpoint: DELETE /api/v1/leads/{email}

URL Parameters:

Success Response (200):

{
  "success": true,
  "message": "Lead deleted successfully."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Error Response (422):

{
  "success": false,
  "message": "The email ID is required and must be a valid email address."
}

Apply Tags to Lead

Applies one or more tags to an existing lead.

Endpoint: POST /api/v1/leads/{email}/tags

URL Parameters:

Request Body:

Example Request:

{
  "tags": [1, 5, 12]
}

Success Response (200):

{
  "success": true,
  "message": "Tags applied successfully."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Remove Tags from Lead

Removes one or more tags from an existing lead.

Endpoint: DELETE /api/v1/leads/{email}/tags

URL Parameters:

Request Body:

Example Request:

{
  "tags": [3, 7]
}

Success Response (200):

{
  "success": true,
  "message": "Tags removed successfully."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Get Lead Fields

Retrieves all available custom fields for leads in your account.

Endpoint: GET /api/v1/leads/fields

Success Response (200):

{
  "success": true,
  "user_lead_fields": [
    {
      "key": "first_name",
      "label": "First Name",
      "type": "text"
    },
    {
      "key": "last_name",
      "label": "Last Name",
      "type": "text"
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "text"
    }
  ]
}

Tags

Get Tags

Retrieves all tags in your account.

Endpoint: GET /api/v1/tags

Success Response (200):

{
  "success": true,
  "tags": [
    {
      "id": 1,
      "name": "Customer"
    },
    {
      "id": 5,
      "name": "Newsletter"
    },
    {
      "id": 12,
      "name": "VIP"
    }
  ]
}

Domains

Domains are read-only in this API. Both endpoints return the built-in Grawt domain (id: -1) and/or verified custom domains belonging to the authenticated account. Alias domains are excluded.

Each domain contains only id, domain (hostname), account_id, is_primary, is_dns_configured, created_at, and updated_at. The built-in domain has is_dns_configured: 1 and null timestamps because it has no separate domain record. Use its id as domain_id when creating a page. A missing or unavailable domain returns 404.

Pages

The Page API manages settings and publishing. It supports custom head and body code, but does not accept or return builder design content, generated page HTML, blocks, or version IDs. Every operation is scoped to the API key's account; do not send account_id.

List Pages

GET /api/v1/pages?domain_id=-1&page=1 returns pages belonging to the API key's account, on the required domain, across all publish statuses, ordered by descending page ID (newest first).

Each page contains up to 20 items; the page size is fixed. In the response, data contains page objects with the same settings, URL, and status as Get Page; current_page, total, and last_page describe pagination. next_page_url, prev_page_url, and pagination links preserve domain_id as you navigate the results. Design content is excluded. An empty domain or a page beyond the final page returns an empty data array with status 200. Missing or malformed domain_id and invalid pagination values return 422. A domain that is unavailable or belongs to another account returns 404.

curl 'https://grawt.app/api/v1/pages?domain_id=-1&page=1' \
  -H 'X-API-Key: your-api-key'

Shared Create and Update Fields

POST and PATCH accept the same settings keys. Creation requires name and domain_id; PATCH leaves omitted fields unchanged. An explicitly supplied null clears a nullable field.

Unknown fields are rejected with 422. The request cannot set publication status; use the publish endpoint.

Create an Empty Page

curl -X POST 'https://grawt.app/api/v1/pages' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"My page","domain_id":-1,"slug":"my-page","title":"My page title"}'

Creation returns a draft with working and published version records. Neither version has body sections or default stacks. Internal editor settings are initialized so the empty page can be opened in the builder and published.

Successful create, get, update, and publish operations return { "page": {...} }; listing returns the paginated response described above. The page contains the settings above plus id, domain (hostname), url, and status (draft, generating, or published). Design data and internal version records are omitted.

Update Settings

curl -X PATCH 'https://grawt.app/api/v1/pages/123' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Updated title","is_index_enabled":true}'

Settings are saved immediately. This does not modify the working or published design.

Publish a Page

curl -X POST 'https://grawt.app/api/v1/pages/123/publish' \
  -H 'X-API-Key: your-api-key'

No body is required. Publishing snapshots and renders the current working version, sets the status to published, clears cached page content, and triggers the existing publication event. The working design remains editable. Empty pages can be published; pages still generating or missing a working version return 422. The latest 15 published snapshots are retained.

Page and Domain Errors

Missing pages, unavailable domains, and resources outside the authenticated account return 404 with { "error": "Page not found." } or { "error": "Domain not found." }.

Page settings validation returns 422:

{
  "error": {
    "slug": ["The page URL already exists under this domain."]
  }
}

Error Handling

Validation response formats are documented per endpoint; page settings use the error field shown above.

Validation Errors (422)

When request validation fails:

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Common Error Codes

Rate Limiting

API requests are subject to rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests response.

Best Practices

Security

• Never expose your API key in client-side code (JavaScript, React, Vue, etc.)
• Store your API key in environment variables on your server
• Use server-to-server communication for API calls

Recommended Architecture

[Client Browser] → [Your Backend Server] → [Grawt API]

Your frontend should submit data to your own backend, which then makes authenticated requests to the Grawt API.

Quick Reference