KORD Agent API

Protocol

One base URL. Predictable request metadata.

Quick start

Connect once, then ask for a post

1. 1

   Copy the complete setup

   In KORD, open the workspace, then go to Settings → Agents → Quick connection. Choose the access level, concrete profiles when using planning or publishing, and an expiry. The 30-day and 90-day options require a separate increased-risk acknowledgement. Accept the warning, create the connection and select Copy complete setup. Paste it once into the intended new private agent task; never use it in a public or shared chat.
2. 2

   Read the token manifest

   The first request tells the agent exactly which operations and scopes are available.

   curl https://app.kord.ch/api/v1/agent/manifest \
     -H "Authorization: Bearer $KORD_WORKSPACE_API_TOKEN"

3. 3

   Read workspace context

   Never invent channel or media IDs. Read the current profiles, permissions, provider restrictions, timezone, recent posts and reusable media first.

   curl "https://app.kord.ch/api/v1/publishing/context?mediaLimit=20&postLimit=20" \
     -H "Authorization: Bearer $KORD_WORKSPACE_API_TOKEN"

4. 4

   Create a draft with an idempotency key

   Use baseText and UUIDs returned by context. Draft creation does not require scheduling or publishing permission.

   curl -X POST https://app.kord.ch/api/v1/publishing/posts \
     -H "Authorization: Bearer $KORD_WORKSPACE_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: campaign-draft-001" \
     -d '{
       "mode": "draft",
       "baseText": "Summer campaign draft",
       "channelIds": ["<channel UUID from context>"],
       "mediaAssetIds": ["<media UUID from context>"],
       "reason": "User asked the agent to prepare a draft."
     }'

5. 5

   Review in KORD

   The response includes the post ID and editor URL. The draft appears in the Draft inbox, where a person can edit it, move it to the calendar, schedule it or publish it.

Recommended workflow

Draft first. Escalate deliberately.

1. 01

   Read the manifest

   Confirm which tools and scopes this exact token may use.

2. 02

   Read publishing context

   Use returned channel IDs, media IDs, permissions, provider restrictions and workspace timezone.

3. 03

   Prepare media

   Reuse an existing asset or upload user-provided media. With media.upload, KORD automatically attaches a compatible copy when an image would otherwise fail the chosen profile format. Inspect visible images for clipped products, people, logos or meaningful text; otherwise mark visual review as pending and return the editor link.

4. 04

   Create a draft

   Use mode: draft by default. The result appears in the workspace Draft inbox for human review.

5. 05

   Read the result

   Use the returned post ID to read status or update the same editable post later.

Permissions

Grant only what the agent needs.

Endpoint reference

Public Agent API endpoints

Post lifecycle

Draft, schedule and publish are explicit modes.

V1 post create and update are draft-only for new Quick and Secure agent connections. Scheduling and publishing use V2 prepare/confirm and run full channel and provider validation before a job is created. Direct elevated V1 publishing exists only for legacy tokens during the controlled flag-off migration window; after cutover it returns token_migration_required. Workspace approval rules can convert an elevated request into a draft pending human approval.

Per-profile variants

Use runtime capabilities, not assumptions.

Each selected profile may receive its own text, media order and options. Read channels[].postTypes, limits, permissions and launch restrictions from publishing context immediately before creating the post. Connected accounts can be more restrictive than the provider's general capability.

The complete schema also covers Facebook Pages, X and LinkedIn, plus current media counts, aspect ratios, text limits and provider launch states. Use the OpenAPI schema for field-level validation and publishing context for account-level availability.

Reliability and errors

Safe retries without duplicate posts.

{
  "status": "error",
  "error": "missing_scope:post.publish",
  "code": "missing_scope",
  "message": "This token is missing the required permission: post.publish.",
  "requestId": "24de532d-878b-441c-9858-0b27142d875e",
  "retryable": false,
  "requiredScopes": ["post.publish"]
}

Optional error fields include details, per-channel issues, requiredScopes, billing limit/maximum and current storage usage. Display message to people and retain code for program logic.

Complete examples

Create a draft from live workspace context.

Both examples discover an active writable profile before creating anything, use a unique idempotency key and stop at a human-reviewable draft. Production clients should also handle rate limits, timeouts and structured errors shown above.

const baseUrl = "https://app.kord.ch/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.KORD_WORKSPACE_API_TOKEN}`,
  "Content-Type": "application/json",
};

const context = await fetch(`${baseUrl}/publishing/context`, { headers })
  .then(async response => {
    if (!response.ok) throw new Error(JSON.stringify(await response.json()));
    return response.json();
  });

const channel = context.data.channels.find(
  item => item.status === "active" && item.permissions.create
);

const draft = await fetch(`${baseUrl}/publishing/posts`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    mode: "draft",
    baseText: "Prepared for human review.",
    channelIds: [channel.id],
    reason: "The user asked the agent to prepare a draft."
  })
}).then(response => response.json());

console.log(draft.data.editorUrl);

import os, uuid, requests

base_url = "https://app.kord.ch/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['KORD_WORKSPACE_API_TOKEN']}"

context = session.get(f"{base_url}/publishing/context")
context.raise_for_status()
channel = next(c for c in context.json()["data"]["channels"]
               if c["status"] == "active" and c["permissions"]["create"])

response = session.post(
    f"{base_url}/publishing/posts",
    headers={"Idempotency-Key": f"draft-{uuid.uuid4()}"},
    json={
        "mode": "draft",
        "baseText": "Prepared for human review.",
        "channelIds": [channel["id"]],
        "reason": "The user asked the agent to prepare a draft.",
    },
)
response.raise_for_status()
print(response.json()["data"]["editorUrl"])

OpenAPI

Machine-readable specification

The OpenAPI 3.1 document defines the current request parameters, request bodies, success responses and errors for generated clients, validation and agent tool discovery. This page remains the readable explanation of the access and safety model.