API docs v1
POST /v1/brands/{brand_id}/tasks

Create a task

scope write:tasks cost 1 RU idempotent required

Create a work item for the brand. New tasks start in the backlog column.

Path parameters

Query parameters

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Header parameters

Request body

application/json required
Type: TaskCreate
  • title string required

    Short task title.

    min length: 1 · max length: 500

  • action_items array of string (nullable) nullable

    Concrete steps to complete the task.

  • category enum (nullable) nullable

    Task category (e.g. CONTENT, TECHNICAL, OUTREACH, SEO).

  • description string (nullable) nullable

    Longer task detail.

  • due_date string (nullable) nullable

    Due date (UTC ISO-8601), if any.

    format: `date-time`

  • effort_level enum (nullable) nullable

    Estimated effort. low, medium, or high.

  • estimated_impact string (nullable) nullable

    Short note on expected impact.

  • external_url string (nullable) nullable

    Link to related work (e.g. a pull request).

  • priority enum

    Priority. One of high, medium, low.

    default: `medium`

  • report_id string (nullable) nullable

    Report this task relates to, if any.

Responses

Created a task application/json
Type: Task
  • title string required

    Short task title.

  • action_items array of string

    Concrete steps to complete the task.

  • agent_session_id string (nullable) nullable

    Agent session working on this task, if any.

  • archived_at string (nullable) nullable

    When the task was archived, if archived.

    format: `date-time`

  • brand_id string (nullable) nullable

    Owning brand id (UUID).

  • brief_id string (nullable) nullable

    Linked content brief id, if any.

  • category string (nullable) nullable

    Task category. One of CONTENT, TECHNICAL, OUTREACH, KNOWLEDGE, MONITORING, SEO.

  • completed_at string (nullable) nullable

    When the task was completed, if done.

    format: `date-time`

  • content_type string (nullable) nullable

    Content type of the linked brief, if any.

  • created_at string (nullable) nullable

    When the task was created.

    format: `date-time`

  • description string (nullable) nullable

    Task detail.

  • due_date string (nullable) nullable

    When the task is due, if set.

    format: `date-time`

  • effort_level string (nullable) nullable

    Estimated effort. One of low, medium, high.

  • estimated_impact string (nullable) nullable

    Estimated impact, e.g. high or a short phrase.

  • external_url string (nullable) nullable

    Linked external URL (e.g. a PR), if any.

  • id string (nullable) nullable

    Task id (UUID). null for tasks returned inline from a cached AI suggestion.

  • object string

    Always task.

    default: `task`

  • pr_url string (nullable) nullable

    URL of the GitHub PR opened for this task, if any.

  • priority string (nullable) nullable

    Priority. One of high, medium, low.

  • report_id string (nullable) nullable

    Report this task was generated from, if any.

  • source_type string (nullable) nullable

    What generated the task (e.g. report, brand_audit, search_console, manual).

  • status string (nullable) nullable

    Workflow status (kanban column). One of backlog, in_progress, review, approved, done.

  • updated_at string (nullable) nullable

    When the task row was last updated.

    format: `date-time`

Example response 
{
  "action_items": [
    "Draft the outline",
    "Add a feature matrix"
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "category": "CONTENT",
  "created_at": "2026-07-01T10:00:00Z",
  "description": "AI answers keep surfacing a rival; a head-to-head page closes the gap.",
  "effort_level": "medium",
  "estimated_impact": "high",
  "id": "a1b2c3d4-1234-4abc-9def-0123456789ab",
  "object": "task",
  "priority": "high",
  "report_id": "c4f8b6a2-9a17-4e31-92fa-7d1e3b5c8b2a",
  "source_type": "report",
  "status": "backlog",
  "title": "Publish a comparison page targeting your top competitor",
  "updated_at": "2026-07-01T10:00:00Z"
}
Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Request body did not match the expected schema application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}