Agent Tasks API | Flint Docs

Overview

The Agent Tasks API allows you to programmatically create and monitor background agent tasks that modify your Flint sites.

Base URL

text

https://app.tryflint.com/api/v1

Billing Requirements

Only available on Enterprise plans.

Authentication

All requests require authentication via API key. Include your API key in the Authorization header:

text

Authorization: Bearer ak_your_api_key_here

API keys can be created in your Flint team settings. Keys are scoped to your organization and require at least member role permissions.

API Keys management dashboard showing a list of keys with creation dates and last-used timestamps

Rate Limiting

These endpoints are rate limited. If you exceed the limit, you'll receive a 429 Too Many Requests response.

POST Create a Task

Start a new background agent task to modify a site.

text

POST /agent/tasks

Request Body

Field	Type	Required	Description
`siteId`	string	Yes	UUID of the site to modify
`prompt`	string	Yes*	Instructions for the agent to follow
`command`	string	No	Command type (e.g., `generate_pages`). If provided, uses command mode instead of prompt mode
`templatePageSlug`	string	No	For `generate_pages`: slug of the template page to use
`items`	array	No	For `generate_pages`: array of up to 10 items to generate (see below)
`callbackUrl`	string	No	HTTPS URL to receive a POST request when the task completes

*Required when not using command mode.

Items Array (for `generate_pages` command)

Each item in the items array accepts:

Field	Type	Required	Description
`targetPageSlug`	string	Yes	The slug for the generated page
`context`	string	Yes	Context or content instructions for this page
`externalId`	string	No	Optional external identifier for tracking

Example Request (prompt mode with callback)

bash

curl -X POST https://app.tryflint.com/api/v1/agent/tasks \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Add a new About page with a team section",
    "callbackUrl": "https://your-server.com/webhooks/flint"
  }'

Example Request (generate_pages command)

bash

curl -X POST https://app.tryflint.com/api/v1/agent/tasks \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "550e8400-e29b-41d4-a716-446655440000",
    "command": "generate_pages",
    "templatePageSlug": "/case-studies/template",
    "items": [
      {
        "targetPageSlug": "/case-studies/acme-corp",
        "context": "Acme Corp increased conversions by 40% using our platform",
        "externalId": "cs-001"
      },
      {
        "targetPageSlug": "/case-studies/globex",
        "context": "Globex reduced time-to-market by 60% with our solution"
      }
    ],
    "callbackUrl": "https://your-server.com/webhooks/flint"
  }'

Success Response (200)

json

{
  "taskId": "bg-550e8400-e29b-41d4-a716-446655440000-a1b2c3d4"
}

Error Responses

Status	Response
400	`{ "error": "Site is missing repository information" }`
400	`{ "error": "Invalid callback URL" }`
404	`{ "error": "Site not found" }`
500	`{ "error": "Failed to start task" }`

GET Get Task Status

Retrieve the current status and results of a task.

text

GET /agent/tasks/{taskId}

Path Parameters

Parameter	Type	Description
`taskId`	string	The task ID from creation

Example Request

bash

curl https://app.tryflint.com/api/v1/agent/tasks/bg-550e8400-a1b2c3d4 \
  -H "Authorization: Bearer ak_your_api_key_here"

Response Formats

The response varies based on task status:

In Progress

json

{
  "taskId": "bg-550e8400-a1b2c3d4",
  "status": "running",
  "phase": "executing"
}

Completed

json

{
  "taskId": "bg-550e8400-a1b2c3d4",
  "status": "completed",
  "output": {
    "pagesCreated": [
      {
        "slug": "/about",
        "previewUrl": "https://your-site-abc123.vercel.app/about",
        "editUrl": "https://app.tryflint.com/app/edit?siteId=...&page=about"
      }
    ],
    "pagesModified": [],
    "pagesDeleted": []
  }
}

Failed

json

{
  "taskId": "bg-550e8400-a1b2c3d4",
  "status": "failed",
  "errorMessage": "Failed to generate page content"
}

Not Found (404)

json

{
  "error": "Task not found"
}

Output Fields

When a task completes successfully, the output object contains:

Field	Type	Description
`pagesCreated`	array	Pages that were newly created
`pagesModified`	array	Existing pages that were updated
`pagesDeleted`	array	Pages that were removed

Each page object contains:

Field	Type	Description
`slug`	string	The page path (e.g., `/about`)
`previewUrl`	string/null	URL to preview the page on the deployment
`editUrl`	string/null	URL to edit the page in the Flint editor

Polling for Completion

Tasks run asynchronously. Poll the GET endpoint to check for completion:

javascript

async function waitForTask(taskId, apiKey) {
  const maxAttempts = 60;
  const delayMs = 5000;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://app.tryflint.com/api/v1/agent/tasks/${taskId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const data = await response.json();

    if (data.status === "completed" || data.status === "failed") {
      return data;
    }

    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("Task timed out");
}

Callback URLs

Instead of polling, you can provide a callbackUrl when creating a task. When the task completes (success or failure), Flint will POST a JSON payload to that URL.

Requirements

•Must use HTTPS
•Internal/private IP addresses and localhost are blocked for security
•If validation fails, the API returns a 400 error

Success Payload

json

{
  "taskId": "bg-550e8400-a1b2c3d4",
  "status": "succeeded",
  "pages": [
    { "slug": "/about", "previewUrl": "https://your-site-abc123.vercel.app/about" }
  ],
  "commitHash": "abc123def456",
  "timestamp": "2026-03-11T12:00:00.000Z"
}

Failure Payload

json

{
  "taskId": "bg-550e8400-a1b2c3d4",
  "status": "failed",
  "error": "Failed to generate page content",
  "timestamp": "2026-03-11T12:00:00.000Z"
}

Payload Fields

Field	Type	Present	Description
`taskId`	string	Always	The task ID matching the one returned at creation
`status`	string	Always	Either `succeeded` or `failed`
`pages`	array	Success only	Array of pages with `slug` and `previewUrl`
`commitHash`	string	Success only	The git commit SHA for the changes
`error`	string	Failure only	Description of what went wrong
`timestamp`	string	Always	ISO 8601 timestamp of completion

Retry Behavior

Flint retries up to 3 times with exponential backoff (starting at 5 seconds) if your server returns a non-2xx response or times out.

Example Webhook Handler (Node.js)

javascript

app.post('/webhooks/flint', (req, res) => {
  const { taskId, status, pages, error } = req.body;
  if (status === 'succeeded') {
    console.log(`Task ${taskId} completed. Pages:`, pages);
  } else {
    console.error(`Task ${taskId} failed:`, error);
  }
  res.sendStatus(200);
});