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

Header parameters

Request body

application/json required
Type:TaskCreate
  • titlestringrequired

    Short task title.

    min length: 1 · max length: 500

  • action_itemsarray of string (nullable)nullable

    Concrete steps to complete the task.

  • categoryenum (nullable)nullable

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

  • descriptionstring (nullable)nullable

    Longer task detail.

  • due_datestring (nullable)nullable

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

    format: `date-time`

  • effort_levelenum (nullable)nullable

    Estimated effort. low, medium, or high.

  • estimated_impactstring (nullable)nullable

    Short note on expected impact.

  • external_urlstring (nullable)nullable

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

  • priorityenum

    Priority. One of high, medium, low.

    default: `medium`

  • report_idstring (nullable)nullable

    Report this task relates to, if any.

Responses

Created a taskapplication/json
Type:Task
  • titlestringrequired

    Short task title.

  • action_itemsarray of string

    Concrete steps to complete the task.

  • agent_session_idstring (nullable)nullable

    Agent session working on this task, if any.

  • archived_atstring (nullable)nullable

    When the task was archived, if archived.

    format: `date-time`

  • brand_idstring (nullable)nullable

    Owning brand id (UUID).

  • brief_idstring (nullable)nullable

    Linked content brief id, if any.

  • categorystring (nullable)nullable

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

  • completed_atstring (nullable)nullable

    When the task was completed, if done.

    format: `date-time`

  • content_typestring (nullable)nullable

    Content type of the linked brief, if any.

  • created_atstring (nullable)nullable

    When the task was created.

    format: `date-time`

  • descriptionstring (nullable)nullable

    Task detail.

  • due_datestring (nullable)nullable

    When the task is due, if set.

    format: `date-time`

  • effort_levelstring (nullable)nullable

    Estimated effort. One of low, medium, high.

  • estimated_impactstring (nullable)nullable

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

  • external_urlstring (nullable)nullable

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

  • idstring (nullable)nullable

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

  • objectstring

    Always task.

    default: `task`

  • pr_urlstring (nullable)nullable

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

  • prioritystring (nullable)nullable

    Priority. One of high, medium, low.

  • report_idstring (nullable)nullable

    Report this task was generated from, if any.

  • source_typestring (nullable)nullable

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

  • statusstring (nullable)nullable

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

  • updated_atstring (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 failedapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 credentialsapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 resourceapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 foundapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 conflictapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 schemaapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 exceededapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 occurredapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 retryapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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"
}