PATCH /v1/brands/{brand_id}/tasks/{task_id}

Update a task

scope write:tasks cost 1 RU idempotent required

Update a task. Only the fields you send change; send status to move it across the board (backlog to in_progress to review to approved to done).

Path parameters

task_idstring required
Task id (UUID).
brand_idstring required
Brand UUID.

Header parameters

Idempotency-Keystring optional

Request body

application/json required

Type:TaskUpdate

action_itemsarray of string (nullable)nullable
Replace the action items.
categoryenum (nullable)nullable
Reclassify the task.
descriptionstring (nullable)nullable
New detail.
due_datestring (nullable)nullable
Change the due date (UTC ISO-8601).

format: `date-time`
effort_levelenum (nullable)nullable
Change the effort estimate.
estimated_impactstring (nullable)nullable
Change the impact note.
external_urlstring (nullable)nullable
Change the related-work link.
priorityenum (nullable)nullable
Change priority.
statusenum (nullable)nullable
Move the task: backlog, in_progress, review, approved, done.
titlestring (nullable)nullable
New title.

Responses

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

Request example

curl --request PATCH \
  --url https://api.rankprompt.com/v1/brands/your_brand_id_here/tasks/your_task_id_here \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/tasks/your_task_id_here';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands/your_brand_id_here/tasks/your_task_id_here"

payload = {}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())