Add a record to an item

POST /boards/{boardId}/items/{itemId}/records

Updated 9 Nov 20264 min read

POST/boards/{boardId}/items/{itemId}/recordsTry it

Basehttps://api.mockflow.com/v1Scopesboards:write

Request

curl https://api.mockflow.com/v1/boards/brd_3f9e2a/items/itm_k9/records \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "record": {
    "title": "Export fails on boards over 200 items",
    "column": "To Do",
    "priority": "high",
    "key": "MF-1482"
  }
}'

const response = await fetch("https://api.mockflow.com/v1/boards/brd_3f9e2a/items/itm_k9/records", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOCKFLOW_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "record": {
    "title": "Export fails on boards over 200 items",
    "column": "To Do",
    "priority": "high",
    "key": "MF-1482"
  }
})
});

const data = await response.json();

import os, requests

response = requests.post(
    "https://api.mockflow.com/v1/boards/brd_3f9e2a/items/itm_k9/records",
    headers={"Authorization": f"Bearer {os.environ['MOCKFLOW_API_KEY']}"},
    json={
  "record": {
    "title": "Export fails on boards over 200 items",
    "column": "To Do",
    "priority": "high",
    "key": "MF-1482"
  }
},
)

response.raise_for_status()
data = response.json()

Response

{
  "id": "itm_k9",
  "type": "string",
  "componentType": "string",
  "boardId": "brd_3f9e2a",
  "sectionId": "string",
  "groupId": "string"
}

{
  "id": "job_7hd2",
  "kind": "item.create",
  "status": "queued",
  "progress": 0,
  "message": "Interview 5 users",
  "result": {
    "itemIds": [
      "string"
    ],
    "updated": [
      "string"
    ],
    "deleted": [
      "string"
    ],
    "creditsUsed": 0,
    "boardTitle": "Q4 Launch Planning",
    "skill": "string"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "The item's type takes no records, the board is locked, or what the item holds could not be read back as it is.",
    "docsUrl": "https://mockflow.com/developers/concepts/errors#conflict"
  },
  "requestId": "req_45d49816999bac40"
}

{
  "error": {
    "code": "validation_failed",
    "message": "data.columns[0].cards[0].priority must be one of low, medium, high",
    "details": [
      {
        "path": "data.columns[0].cards[0].priority",
        "expected": [
          "low",
          "medium",
          "high"
        ]
      }
    ]
  },
  "requestId": "req_01j9"
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "docsUrl": "https://mockflow.com/developers/concepts/errors#rate_limited"
  },
  "requestId": "req_45d49816999bac40"
}

Adds one thing to an item that holds many: a card to a kanban (in the column it names), a task to a gantt, an event to a timeline or calendar, an item to a checklist, a line to a document, a value to a chart, a row to a spreadsheet. Send the same key again and that record is updated and moved instead of added twice; without a key, a record identical to one already there changes nothing. Everything else in the item stays as it is. What a type takes is record on GET /item-types/{type}; types without it answer 409.

Authorization

Authorizationstringheaderrequired

Bearer <key>. The key needs boards:write scope. Create and manage keys in the developer console, or use an OAuth app to act for other people; what each scope unlocks is on the scopes page.

Path parameters

boardIdstringpathrequired

itemIdstringpathrequired

Body

application/json

callbackUrlstring

Optional. When the job this request starts finishes or fails, a short body is POSTed here once: { eventId, status, boardId, boardUrl, imageUrl }, where status is succeeded or failed and imageUrl is a picture of what the job drew, or null. Signed with the workspace's callback secret (GET /webhooks/callback-secret). https to a public host. The full job is on GET /jobs/{jobId}.

recordItemRecordrequired

Selected by the type of the item it is added to. One schema per type that takes records.

Response

200 · application/json

idstring

typestring

An ItemType, or other for an editor widget the API has no type for.

componentTypestring

The editor's own class name, exact where type is a family.

boardIdstring

sectionIdstring | null

The section the item sits inside, by position.

groupIdstring | null

positionPoint

Child attributes

xnumberrequired

ynumberrequired

sizeSize

Child attributes

widthnumber

heightnumber

rotationnumber

zIndexinteger

lockedboolean

textstring

Plain text extracted from the item, for search and the outline.

readbackenum<string>

One of exact, unwrapped, text, pointer, parts or none.

dataItemData

Selected by the sibling type. One schema per item type, generated from the component registry.

fromstring | null

Connectors only: the item or group: the line starts at.

tostring | null

Connectors only.

directedboolean

Connectors only.

labelstring

Connectors only.

urlstring

Opens the board focused on this item.

changedboolean

Errors

409conflict

The item's type takes no records, the board is locked, or what the item holds could not be read back as it is.

422validation_failed

The body did not match the schema for this item type.

429rate_limited

Too many requests.

Was this page helpful?