Recipes

export API=http://localhost:3000/api
export TOKEN="the token from My account → Security"
auth=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")

# 1. the workspace, born with the 5 default columns
TENANT=$(curl -s "${auth[@]}" -X POST $API/tenants \
  -d '{ "name": "Support", "color": "sky" }' | jq -r .id)

# 2. the entry column, from the workspace set
COLUMN=$(curl -s "${auth[@]}" "$API/columns?tenant=$TENANT" | jq -r '.[0].id')

# 3. project and label
PROJECT=$(curl -s "${auth[@]}" -X POST $API/projects \
  -d "{ \"tenantId\": \"$TENANT\", \"name\": \"Integrations\" }" | jq -r .id)

TAG=$(curl -s "${auth[@]}" -X POST $API/tags \
  -d "{ \"tenantId\": \"$TENANT\", \"name\": \"api\" }" | jq -r .id)

# 4. the epic, which inherits the project's workspace
EPIC=$(curl -s "${auth[@]}" -X POST $API/epics \
  -d "{ \"projectId\": \"$PROJECT\", \"name\": \"Onboarding\" }" | jq -r .id)

# 5. the card
curl -s "${auth[@]}" -X POST $API/cards \
  -d "{
    \"tenantId\": \"$TENANT\",
    \"title\": \"Publish the documentation\",
    \"columnId\": \"$COLUMN\",
    \"projectId\": \"$PROJECT\",
    \"epicId\": \"$EPIC\",
    \"tagIds\": [\"$TAG\"]
  }"

const API = "http://localhost:3000/api";
const token = process.env.NOTEBUGS_TOKEN!;

async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(API + path, {
    ...init,
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
      ...init.headers,
    },
  });

  // The HTTP code is the contract; `error` is the sentence for readers.
  if (!response.ok) {
    const { error } = await response.json();
    throw new Error(`${response.status}: ${error}`);
  }

  return response.json();
}

const tenant = await api<{ id: string }>("/tenants", {
  method: "POST",
  body: JSON.stringify({ name: "Support", color: "sky" }),
});

const columns = await api<{ id: string }[]>(`/columns?tenant=${tenant.id}`);

const project = await api<{ id: string }>("/projects", {
  method: "POST",
  body: JSON.stringify({ tenantId: tenant.id, name: "Integrations" }),
});

const card = await api("/cards", {
  method: "POST",
  body: JSON.stringify({
    tenantId: tenant.id,
    title: "Publish the documentation",
    columnId: columns[0].id,
    projectId: project.id,
  }),
});

# multipart: with no hand-written Content-Type, curl writes the boundary
curl -s -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]" \
  $API/cards/$CARD/attachments

# the response carries the url ready for Markdown
# [screenshot](/api/files/18ab694d-….png)

const form = new FormData();
form.append("files", file);

const response = await fetch(`${API}/cards/${cardId}/attachments`, {
  method: "POST",
  // No Content-Type: FormData writes the boundary itself.
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});

const [attachment] = await response.json();
console.log(attachment.url); // /api/files/<server-generated name>.png