API reference
Base URL https://marca.dev/api/v1 · version 1.0.0 · openapi.json. Authentication, scopes and on-behalf-of are explained in API & tokens.
Identity
get/projects/{projectToken}/whoami
Describe the calling credential
Who this credential acts as, its role and scopes, and when it expires. Works for every credential kind.
Returns 200 The credential.
Tasks
get/projects/{projectToken}/tasksscope tasks:read
List tasks
Top-level tasks, oldest first. `?include=subtasks` returns every task.
include(query)
Returns 200 Tasks.
post/projects/{projectToken}/tasksscope tasks:write
Create a task
X-Marca-On-Behalf-Of(header) — API keys only: the workspace member this request acts for, as `user_<id>` or their email. Required for writes made with an API key; the request then has that member’s role.
Schema
{
"type": "object",
"properties": {
"route": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^\\/[^\\x00-\\x1F\\x7F]*$"
},
"originUrl": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"anchor": {
"anyOf": [
{
"type": "object",
"properties": {
"srcLoc": {
"type": "string",
"maxLength": 2048
},
"id": {
"type": "string",
"maxLength": 2048
},
"testId": {
"type": "string",
"maxLength": 2048
},
"name": {
"type": "string",
"maxLength": 2048
},
"role": {
"type": "string",
"maxLength": 64
},
"accessibleName": {
"type": "string",
"maxLength": 400
},
"tag": {
"type": "string",
"maxLength": 64
},
"href": {
"type": "string",
"maxLength": 2048
},
"src": {
"type": "string",
"maxLength": 2048
},
"alt": {
"type": "string",
"maxLength": 400
},
"text": {
"type": "string",
"maxLength": 400
},
"cssSelector": {
"type": "string",
"maxLength": 2048
},
"landmark": {
"type": "object",
"properties": {
"tag": {
"type": "string",
"maxLength": 64
},
"label": {
"type": "string",
"maxLength": 200
}
},
"required": [
"tag"
],
"additionalProperties": false
},
"bbox": {
"type": "object",
"properties": {
"xPct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"yPct": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"xPct",
"yPct"
],
"additionalProperties": false
}
},
"required": [
"tag"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"selector": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"elementText": {
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
]
},
"viewportWidth": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"viewportHeight": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"instruction": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"assignedToEmail": {
"anyOf": [
{
"type": "string",
"format": "email",
"maxLength": 320
},
{
"type": "null"
}
]
},
"priority": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
"mentions": {
"type": "array",
"items": {
"type": "string",
"format": "email",
"maxLength": 320
},
"maxItems": 50
},
"sourceCommentId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"capturedLogs": {
"anyOf": [
{
"type": "object",
"properties": {
"capturedAt": {
"type": "string",
"format": "date-time"
},
"pageUrl": {
"type": "string",
"maxLength": 2048
},
"console": {
"type": "array",
"items": {
"type": "object",
"properties": {
"t": {
"type": "number"
},
"level": {
"type": "string",
"enum": [
"log",
"info",
"warn",
"error",
"debug"
]
},
"text": {
"type": "string",
"maxLength": 1100
}
},
"required": [
"t",
"level",
"text"
],
"additionalProperties": false
},
"maxItems": 100
},
"network": {
"type": "array",
"items": {
"type": "object",
"properties": {
"t": {
"type": "number"
},
"method": {
"type": "string",
"maxLength": 16
},
"url": {
"type": "string",
"maxLength": 1200
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 999
},
{
"type": "null"
}
]
},
"ok": {
"type": "boolean"
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "string",
"maxLength": 600
}
},
"required": [
"t",
"method",
"url",
"status",
"ok",
"durationMs"
],
"additionalProperties": false
},
"maxItems": 50
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"t": {
"type": "number"
},
"message": {
"type": "string",
"maxLength": 600
},
"stack": {
"type": "string",
"maxLength": 2200
},
"source": {
"type": "string",
"maxLength": 1200
}
},
"required": [
"t",
"message"
],
"additionalProperties": false
},
"maxItems": 30
}
},
"required": [
"capturedAt",
"pageUrl",
"console",
"network",
"errors"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"route",
"instruction"
],
"additionalProperties": false
}Returns 201 The new task.
get/projects/{projectToken}/tasks/{taskId}scope tasks:read
Get a task with its comments and subtasks
taskId(path, required)
Returns 200 The task.
patch/projects/{projectToken}/tasks/{taskId}scope tasks:write
Update a task
Change status, instruction, assignee or priority. Needs a role that can edit tasks.
taskId(path, required)X-Marca-On-Behalf-Of(header) — API keys only: the workspace member this request acts for, as `user_<id>` or their email. Required for writes made with an API key; the request then has that member’s role.
Schema
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"pending",
"in_progress",
"in_review",
"approved",
"done",
"cancelled"
]
},
"instruction": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"assignedToEmail": {
"anyOf": [
{
"type": "string",
"format": "email",
"maxLength": 320
},
{
"type": "null"
}
]
},
"priority": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
}
},
"additionalProperties": false
}Returns 200 Updated.
post/projects/{projectToken}/tasks/bulk-statusscope tasks:write
Move several items to one status
Comments in `items` are promoted to tasks first.
X-Marca-On-Behalf-Of(header) — API keys only: the workspace member this request acts for, as `user_<id>` or their email. Required for writes made with an API key; the request then has that member’s role.
Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "task"
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "comment"
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"type",
"id"
],
"additionalProperties": false
}
]
},
"minItems": 1,
"maxItems": 500
},
"status": {
"type": "string",
"enum": [
"pending",
"in_progress",
"in_review",
"approved",
"done",
"cancelled"
]
}
},
"required": [
"items",
"status"
],
"additionalProperties": false
}Returns 200 The batch.
post/projects/{projectToken}/tasks/{taskId}/subtasksscope tasks:write
Create a subtask
taskId(path, required)X-Marca-On-Behalf-Of(header) — API keys only: the workspace member this request acts for, as `user_<id>` or their email. Required for writes made with an API key; the request then has that member’s role.
Schema
{
"type": "object",
"properties": {
"instruction": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"assignedToEmail": {
"anyOf": [
{
"type": "string",
"format": "email",
"maxLength": 320
},
{
"type": "null"
}
]
},
"priority": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
"mentions": {
"type": "array",
"items": {
"type": "string",
"format": "email",
"maxLength": 320
},
"maxItems": 50
}
},
"required": [
"instruction"
],
"additionalProperties": false
}Returns 201 The new subtask.
post/projects/{projectToken}/tasks/{taskId}/commentsscope tasks:write
Comment on a task
taskId(path, required)X-Marca-On-Behalf-Of(header) — API keys only: the workspace member this request acts for, as `user_<id>` or their email. Required for writes made with an API key; the request then has that member’s role.
Schema
{
"type": "object",
"properties": {
"body": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"mentions": {
"type": "array",
"items": {
"type": "string",
"format": "email",
"maxLength": 320
},
"maxItems": 50
}
},
"required": [
"body"
],
"additionalProperties": false
}Returns 201 The comment.
Review feed
get/projects/{projectToken}/itemsscope tasks:read
The review feed: open tasks and unpromoted comments
status(query)
Returns 200 Items.
Comments
get/projects/{projectToken}/commentsscope tasks:read
List page comments
Returns 200 Comments.
post/projects/{projectToken}/commentsscope comments:write
Pin a comment on a page
X-Marca-On-Behalf-Of(header) — API keys only: the workspace member this request acts for, as `user_<id>` or their email. Required for writes made with an API key; the request then has that member’s role.
Schema
{
"type": "object",
"properties": {
"anchorType": {
"type": "string",
"const": "route"
},
"route": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^\\/[^\\x00-\\x1F\\x7F]*$"
},
"originUrl": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"anchor": {
"anyOf": [
{
"type": "object",
"properties": {
"srcLoc": {
"type": "string",
"maxLength": 2048
},
"id": {
"type": "string",
"maxLength": 2048
},
"testId": {
"type": "string",
"maxLength": 2048
},
"name": {
"type": "string",
"maxLength": 2048
},
"role": {
"type": "string",
"maxLength": 64
},
"accessibleName": {
"type": "string",
"maxLength": 400
},
"tag": {
"type": "string",
"maxLength": 64
},
"href": {
"type": "string",
"maxLength": 2048
},
"src": {
"type": "string",
"maxLength": 2048
},
"alt": {
"type": "string",
"maxLength": 400
},
"text": {
"type": "string",
"maxLength": 400
},
"cssSelector": {
"type": "string",
"maxLength": 2048
},
"landmark": {
"type": "object",
"properties": {
"tag": {
"type": "string",
"maxLength": 64
},
"label": {
"type": "string",
"maxLength": 200
}
},
"required": [
"tag"
],
"additionalProperties": false
},
"bbox": {
"type": "object",
"properties": {
"xPct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"yPct": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
"required": [
"xPct",
"yPct"
],
"additionalProperties": false
}
},
"required": [
"tag"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"viewport": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"profile": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"xPct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"yPct": {
"type": "number",
"minimum": 0,
"maximum": 100
},
"sourceWidth": {
"type": "integer",
"exclusiveMinimum": 0
},
"sourceHeight": {
"type": "integer",
"exclusiveMinimum": 0
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"capturedLogs": {
"anyOf": [
{
"type": "object",
"properties": {
"capturedAt": {
"type": "string",
"format": "date-time"
},
"pageUrl": {
"type": "string",
"maxLength": 2048
},
"console": {
"type": "array",
"items": {
"type": "object",
"properties": {
"t": {
"type": "number"
},
"level": {
"type": "string",
"enum": [
"log",
"info",
"warn",
"error",
"debug"
]
},
"text": {
"type": "string",
"maxLength": 1100
}
},
"required": [
"t",
"level",
"text"
],
"additionalProperties": false
},
"maxItems": 100
},
"network": {
"type": "array",
"items": {
"type": "object",
"properties": {
"t": {
"type": "number"
},
"method": {
"type": "string",
"maxLength": 16
},
"url": {
"type": "string",
"maxLength": 1200
},
"status": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 999
},
{
"type": "null"
}
]
},
"ok": {
"type": "boolean"
},
"durationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"error": {
"type": "string",
"maxLength": 600
}
},
"required": [
"t",
"method",
"url",
"status",
"ok",
"durationMs"
],
"additionalProperties": false
},
"maxItems": 50
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"t": {
"type": "number"
},
"message": {
"type": "string",
"maxLength": 600
},
"stack": {
"type": "string",
"maxLength": 2200
},
"source": {
"type": "string",
"maxLength": 1200
}
},
"required": [
"t",
"message"
],
"additionalProperties": false
},
"maxItems": 30
}
},
"required": [
"capturedAt",
"pageUrl",
"console",
"network",
"errors"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"anchorType",
"route",
"viewport",
"profile",
"xPct",
"yPct",
"sourceWidth",
"sourceHeight",
"body"
],
"additionalProperties": false
}Returns 201 The comment.
Webhooks
get/projects/{projectToken}/webhooksscope webhooks:manage
List webhook endpoints
Returns 200 Endpoints.
post/projects/{projectToken}/webhooksscope webhooks:manage
Create a webhook endpoint
The URL must be a public https address. The signing secret is returned once.
Schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"task.created",
"task.updated",
"task.status_changed",
"task.comment_added",
"comment.created",
"export.created",
"manifest.published"
]
},
"minItems": 1,
"maxItems": 7
},
"description": {
"type": "string",
"maxLength": 200
}
},
"required": [
"url",
"events"
],
"additionalProperties": false
}Returns 201 The endpoint and its secret.
patch/projects/{projectToken}/webhooks/{webhookId}scope webhooks:manage
Update, disable or rotate a webhook endpoint
webhookId(path, required)
Schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"task.created",
"task.updated",
"task.status_changed",
"task.comment_added",
"comment.created",
"export.created",
"manifest.published"
]
},
"minItems": 1,
"maxItems": 7
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"rotateSecret": {
"type": "boolean"
}
},
"additionalProperties": false
}Returns 200 The endpoint (and new secret when rotated).
delete/projects/{projectToken}/webhooks/{webhookId}scope webhooks:manage
Delete a webhook endpoint
webhookId(path, required)
Returns 204 Deleted.
get/projects/{projectToken}/webhooks/{webhookId}/deliveriesscope webhooks:manage
Recent deliveries for an endpoint
webhookId(path, required)
Returns 200 Deliveries, newest first.
post/projects/{projectToken}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliverscope webhooks:manage
Queue a delivery again
webhookId(path, required)deliveryId(path, required)
Returns 200 Re-queued.
post/projects/{projectToken}/webhooks/{webhookId}/testscope webhooks:manage
Send a ping to an endpoint
webhookId(path, required)
Returns 202 Queued.
Webhook events
Configure endpoints in a project’s Integrations tab or with the webhook routes above. See Webhooks for signatures and retries.
task.created
A task or subtask was created
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "task.created"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}task.updated
A task’s instruction, assignee or priority changed
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "task.updated"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}task.status_changed
A task moved to another status
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "task.status_changed"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}task.comment_added
Someone commented on a task
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "task.comment_added"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}comment.created
A reviewer pinned a comment on a page
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "comment.created"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}export.created
Items were exported (one event per export)
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "export.created"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}manifest.published
A crawl published a new set of pages
Schema
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"project",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event id; the same across retries of one delivery"
},
"type": {
"type": "string",
"const": "manifest.published"
},
"createdAt": {
"type": "string",
"description": "ISO 8601"
},
"project": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
}
},
"actor": {
"type": "object",
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
}
}
},
"data": {
"type": "object",
"description": "Event-specific: `task` (+ `change` or `comment`), `comment`, export `batchId` + `taskIds`, or manifest details"
}
}
}