Fishladder API

Authentication

All API requests require a Bearer token. Generate one at Settings → API Keys. Each key is scoped to a single team — to access multiple teams, generate a key for each one.

curl https://app.ladder.fish/api/v1/projects \
  -H "Authorization: Bearer fl_your_key_here"

Rate Limits

Per API key, per hour: 1,000 reads (GET) and 200 writes (POST/PUT/PATCH/DELETE). The two budgets are separate, so exhausting reads does not block writes, and each key has its own — one busy integration cannot starve another. Exceeded requests return 429 Too Many Requests with a Retry-After header and a scope field naming which budget ran out.

Errors

All errors return JSON with an error field.

{ "error": "Not found" }

Projects

Local projects — roadmap items created directly in Fishladder (not synced from Linear).

Fields

Example

# Create a project
curl -X POST https://app.ladder.fish/api/v1/projects \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rebuild onboarding flow",
    "status": "planned",
    "kanbanColumn": "q2-2026",
    "targetDate": "2026-06-30"
  }'

# Response (201)
{
  "id": "local-550e8400-...",
  "title": "Rebuild onboarding flow",
  "description": "",
  "status": "planned",
  "initiativeId": null,
  "kanbanColumn": "q2-2026",
  "kanbanRowId": null,
  "startDate": null,
  "targetDate": "2026-06-30",
  "trackerProjectId": null,
  "issueStatuses": [],
  "createdAt": "2026-03-04T10:00:00.000Z"
}

# Link a tracker project (task statuses then appear on the roadmap card)
curl -X PUT https://app.ladder.fish/api/v1/projects/local-550e8400-... \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "trackerProjectId": "tracker-91a34cd0-..." }'

Tasks

Tracker tasks — work items within tracker projects.

Boards in a project group are only reachable by keys whose owner can open that group: other boards' tasks answer 404, as if they didn't exist. An assigneeId must be an active member who can open the board, otherwise the request is refused with 400.

Fields

Example

# Create a task
curl -X POST https://app.ladder.fish/api/v1/tasks \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review Q2 metrics",
    "projectId": "proj-abc123",
    "priority": "high",
    "dueDate": "2026-04-15"
  }'

# Partially update a task
curl -X PATCH https://app.ladder.fish/api/v1/tasks/task-uuid \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "dueDate": "2026-04-10" }'

# Mark complete
curl -X PATCH https://app.ladder.fish/api/v1/tasks/task-uuid \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "done" }'

# Delete
curl -X DELETE https://app.ladder.fish/api/v1/tasks/task-uuid \
  -H "Authorization: Bearer fl_your_key_here"
# Response: { "ok": true }

Tracker Projects

Projects within the Tracker app. Use these IDs when creating or listing tasks.

Response Fields

Example

curl https://app.ladder.fish/api/v1/tracker/projects \
  -H "Authorization: Bearer fl_your_key_here"

# Response
[
  {
    "id": "proj-abc123",
    "name": "Acme Corp",
    "groupId": "grp-xyz",
    "groupName": "CSM",
    "color": "#6366f1",
    "icon": null,
    "archived": false,
    "sortOrder": 0
  }
]

Sections & Statuses

Board columns (sections) and workflow statuses for a tracker project. Use these to discover valid sectionId/statusId values for task create/update — API-created tasks land in the first section (Backlog) unless placed explicitly.

Example

curl https://app.ladder.fish/api/v1/tracker/projects/proj-abc123/statuses \
  -H "Authorization: Bearer fl_your_key_here"

# Response
[
  { "id": "st-1", "projectId": "proj-abc123", "name": "Todo", "color": "#6B7280", "sortOrder": 0, "isDefault": true,  "isClosed": false },
  { "id": "st-2", "projectId": "proj-abc123", "name": "In Progress", "color": "#3B82F6", "sortOrder": 1, "isDefault": false, "isClosed": false },
  { "id": "st-3", "projectId": "proj-abc123", "name": "Done", "color": "#22C55E", "sortOrder": 2, "isDefault": false, "isClosed": true }
]

Calendar — What's Due

Everything due or scheduled in a time frame, across modules: task due dates, roadmap project target dates, deal expected-close dates, quote expirations, interviews, questionnaire due dates, audit milestones and calendar events. Requires the Calendar module. Finished work is left out unless you ask for it.

Query Parameters

Returns 400 for a malformed or out-of-range date (days beyond ±400, years outside 1900–2200), end together with days, an unknown type, more than 50 projects, or projects combined with only non-project types (projects carry tasks and target dates only). Reads count against the normal v1 read limit.

Response Fields

Example

# Everything due for the Acme project in the next 30 days
curl "https://app.ladder.fish/api/v1/calendar?days=30&projects=Acme&timezone=America/New_York" \
  -H "Authorization: Bearer fl_your_key_here"

# Response
{
  "range": { "start": "2026-09-27", "end": "2026-10-26" },
  "types": ["task", "roadmap"],
  "projects": {
    "matched": [{ "ref": "Acme", "kind": "board", "id": "proj-abc123", "name": "Acme Corp" }],
    "unmatched": []
  },
  "includeCompleted": false,
  "count": 2,
  "truncated": false,
  "counts": { "task": 1, "roadmap": 1 },
  "items": [
    {
      "id": "task-1", "type": "task", "typeLabel": "Tasks",
      "title": "Kickoff deck", "date": "2026-10-02", "time": null,
      "status": "In Progress", "completed": false,
      "project": { "id": "proj-abc123", "name": "Acme Corp" }, "company": null,
      "url": "https://app.ladder.fish/projects/proj-abc123/board?task=task-1"
    },
    {
      "id": "rm-9", "type": "roadmap", "typeLabel": "Project target dates",
      "title": "Target: Acme go-live", "date": "2026-10-20", "time": null,
      "status": "in_progress", "completed": false,
      "project": { "id": "proj-abc123", "name": "Acme Corp" }, "company": null,
      "url": "https://app.ladder.fish/kanban"
    }
  ]
}

# Deals closing and quotes expiring this month
curl "https://app.ladder.fish/api/v1/calendar?start=2026-10-01&end=2026-10-31&types=crm_close,cpq_expiry" \
  -H "Authorization: Bearer fl_your_key_here"

Initiatives

Local initiatives — group multiple projects under a strategic theme.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/initiatives \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Platform reliability", "color": "#6366f1" }'

Feedback

Customer feedback entries. New entries are automatically appended at the lowest priority.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/feedback \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Export to CSV",
    "details": "Several enterprise customers have asked for CSV export.",
    "names": ["Acme Corp", "Globex"],
    "impact": "high",
    "status": "open"
  }'

Goals

Strategic goals. The GET endpoint returns both goals and their item links in one response.

Fields

Example

# GET response shape
{
  "goals": [
    {
      "id": "abc123",
      "title": "Improve retention by 20%",
      "description": "",
      "color": "#6366f1",
      "status": "active",
      "categoryIds": [],
      "sortOrder": 0,
      "createdAt": "2026-03-04T10:00:00.000Z"
    }
  ],
  "links": [
    { "goalId": "abc123", "itemId": "local-xyz" }
  ]
}

Theme Rows

Theme rows appear as horizontal swimlanes in the Kanban view. Projects and initiatives are assigned to a row via kanbanRowId.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/rows \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Platform", "goal": "Improve infrastructure reliability" }'

# Response (201)
{ "id": "550e8400-...", "name": "Platform", "goal": "Improve infrastructure reliability", "sortOrder": 2 }

Your key

Who a key belongs to, which team it acts on, and which teams its owner can reach. A key is bound to exactly one team, fixed when it was created — these endpoints are how you tell which.

Response Fields — /api/v1/me

Response Fields — /api/v1/me/teams

Example

curl https://app.ladder.fish/api/v1/me/teams \
  -H "Authorization: Bearer fl_your_key_here"

# Response
{
  "teams": [
    { "id": "org_abc", "name": "Acme", "role": "admin", "apps": ["roadmap", "tracker"], "current": true },
    { "id": "org_xyz", "name": "Northwind", "role": "member", "apps": ["tracker"], "current": false }
  ],
  "current": "org_abc"
}

A key resolves its creator's access on every request, so demoting them — or revoking a module — narrows the key immediately. Role and modules differ per team, which is why each entry carries its own.

Members

Read-only list of team members.

Response Fields

Example

curl https://app.ladder.fish/api/v1/members \
  -H "Authorization: Bearer fl_your_key_here"

# Response
[
  {
    "id": "user_abc",
    "name": "Jane Smith",
    "email": "[email protected]",
    "avatarUrl": "https://...",
    "role": "admin",
    "jobTitle": "Engineering Manager",
    "department": "Engineering"
  }
]

Member Profiles

Update job title and department for team members. Admin-only.

Request Body

Example

curl -X PUT https://app.ladder.fish/api/admin/member-profiles \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc",
    "jobTitle": "Senior Engineer",
    "department": "Engineering"
  }'

# Response
{ "ok": true }

Jobs

Hiring jobs (positions). Creating a job automatically generates default pipeline stages.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/jobs \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Frontend Engineer",
    "department": "Engineering",
    "location": "San Francisco",
    "type": "full-time",
    "remotePolicy": "hybrid",
    "status": "open"
  }'

# Response (201)
{
  "id": "abc123",
  "title": "Senior Frontend Engineer",
  "department": "Engineering",
  "location": "San Francisco",
  "type": "full-time",
  "remotePolicy": "hybrid",
  "status": "open",
  "salaryMin": null,
  "salaryMax": null,
  "salaryCurrency": "USD",
  "description": null,
  "requirements": null,
  "publishedAt": null,
  "closedAt": null,
  "sortOrder": 0,
  "createdAt": "2026-03-06T10:00:00.000Z",
  "updatedAt": "2026-03-06T10:00:00.000Z"
}

Candidates

People in your hiring pipeline. Candidates can be applied to one or more jobs via applications.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/candidates \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "linkedinUrl": "https://linkedin.com/in/janesmith",
    "source": "referral"
  }'

# Response (201)
{
  "id": "cand-abc123",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": null,
  "linkedinUrl": "https://linkedin.com/in/janesmith",
  "portfolioUrl": null,
  "location": null,
  "source": "referral",
  "sourceDetail": null,
  "resumeUrl": null,
  "avatarUrl": null,
  "tags": [],
  "createdAt": "2026-03-06T10:00:00.000Z",
  "updatedAt": "2026-03-06T10:00:00.000Z"
}

Applications

An application connects a candidate to a job. Move candidates through pipeline stages by updating the stageId.

Fields

Example

# Apply a candidate to a job
curl -X POST https://app.ladder.fish/api/v1/applications \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job-abc123",
    "candidateId": "cand-def456",
    "stageId": "job-abc123-stage-0"
  }'

# Move candidate to next stage
curl -X PUT https://app.ladder.fish/api/v1/applications/app-xyz \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "stageId": "job-abc123-stage-1" }'

# Mark as hired
curl -X PUT https://app.ladder.fish/api/v1/applications/app-xyz \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "hired" }'

Custom Fields

Custom fields let you add team-specific data to tasks, projects, and candidates. Define fields in Settings → Custom Fields, then read and write values via the API.

Field definition shape

Reading custom fields

All GET responses for tasks, candidates, and projects include a customFields object. Keys are field names, values are typed (string, number, boolean, string[]).

// GET /api/v1/tasks response
{
  "id": "task-abc",
  "title": "Review Q2 metrics",
  "customFields": {
    "Priority Score": 85,
    "Region": "EMEA",
    "Approved": true
  }
}

Writing custom fields

Include a customFields object on POST or PUT requests. Use field names as keys. Unknown field names return a 400 error. Formula fields are read-only (computed automatically).

curl -X POST https://app.ladder.fish/api/v1/tasks \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review Q2 metrics",
    "projectId": "proj-abc123",
    "customFields": {
      "Priority Score": 85,
      "Region": "EMEA",
      "Approved": true
    }
  }'

List definitions

curl "https://app.ladder.fish/api/v1/custom-fields?entityType=task" \
  -H "Authorization: Bearer fl_your_key_here"

# Response
[
  {
    "id": "cf-abc",
    "entityType": "task",
    "name": "Priority Score",
    "fieldType": "number",
    "options": null,
    "config": { "numberFormat": { "format": "plain", "precision": 0 } },
    "required": false,
    "sortOrder": 0
  }
]

CRM Contacts

People in your CRM. Contacts can be linked to companies, deals, and activities.

Fields

Response Fields (read-only)

Example

curl -X POST https://app.ladder.fish/api/v1/crm/contacts \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "title": "VP of Engineering",
    "source": "linkedin",
    "lifecycleStage": "prospecting"
  }'

# Response (201)
{
  "id": "Cabc123-...",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": null,
  "title": "VP of Engineering",
  "companyId": null,
  "companyName": null,
  "source": "linkedin",
  "lifecycleStage": "prospecting",
  "tags": [],
  "ownerId": null,
  "linkedinUrl": null,
  "createdAt": "2026-03-13T10:00:00.000Z",
  "updatedAt": "2026-03-13T10:00:00.000Z"
}

CRM Companies

Organizations in your CRM. Companies can be linked to contacts and deals.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/crm/companies \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "domain": "acme.com",
    "industry": "SaaS",
    "size": "51-200",
    "website": "https://acme.com"
  }'

# Response (201)
{
  "id": "Aabc123-...",
  "name": "Acme Corp",
  "domain": "acme.com",
  "industry": "SaaS",
  "size": "51-200",
  "website": "https://acme.com",
  "phone": null,
  "addressLine1": null,
  "addressLine2": null,
  "city": null,
  "state": null,
  "country": null,
  "postalCode": null,
  "lifecycleStage": "prospecting",
  "tags": [],
  "ownerId": null,
  "logoUrl": null,
  "trackerProjectId": null,
  "createdAt": "2026-03-13T10:00:00.000Z",
  "updatedAt": "2026-03-13T10:00:00.000Z"
}

CRM Deals

Revenue opportunities in your pipeline. Deals are linked to a pipeline and can be associated with contacts and companies.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/crm/deals \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme Corp — Enterprise Plan",
    "value": 12000000,
    "currency": "USD",
    "pipelineId": "pipe-abc123",
    "companyId": "company-abc123",
    "contactId": "contact-abc123",
    "probability": 60,
    "expectedCloseDate": "2026-06-30"
  }'

# Response (201)
{
  "id": "deal-abc123",
  "title": "Acme Corp — Enterprise Plan",
  "value": 12000000,
  "currency": "USD",
  "pipelineId": "pipe-abc123",
  "stageId": "stage-qualified",
  "companyId": "company-abc123",
  "contactId": "contact-abc123",
  "ownerId": null,
  "probability": 60,
  "expectedCloseDate": "2026-06-30",
  "status": "open",
  "lostReason": null,
  "tags": [],
  "createdAt": "2026-03-13T10:00:00.000Z",
  "updatedAt": "2026-03-13T10:00:00.000Z"
}

CRM Pipelines

Sales pipelines define the stages a deal moves through. Creating a pipeline automatically creates default stages.

Fields

Creating a pipeline automatically creates default stages: Qualified, Meeting Booked, Proposal Sent, Negotiation, Closed Won, and Closed Lost.

Example

curl -X POST https://app.ladder.fish/api/v1/crm/pipelines \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Sales",
    "isDefault": false
  }'

# Response (201)
{
  "id": "pipe-abc123",
  "name": "Enterprise Sales",
  "isDefault": false,
  "stages": [
    { "id": "stage-1", "name": "Qualified", "order": 0 },
    { "id": "stage-2", "name": "Meeting Booked", "order": 1 },
    { "id": "stage-3", "name": "Proposal Sent", "order": 2 },
    { "id": "stage-4", "name": "Negotiation", "order": 3 },
    { "id": "stage-5", "name": "Closed Won", "order": 4 },
    { "id": "stage-6", "name": "Closed Lost", "order": 5 }
  ],
  "createdAt": "2026-03-13T10:00:00.000Z",
  "updatedAt": "2026-03-13T10:00:00.000Z"
}

CRM Activities

Log calls, emails, meetings, notes, and tasks against contacts, companies, and deals.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/crm/activities \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "meeting",
    "subject": "Discovery call with Acme",
    "body": "Discussed enterprise plan requirements and timeline.",
    "durationMins": 45,
    "contactId": "contact-abc123",
    "companyId": "company-abc123",
    "dealId": "deal-abc123",
    "completedAt": "2026-03-13T14:00:00.000Z"
  }'

# Response (201)
{
  "id": "activity-abc123",
  "type": "meeting",
  "subject": "Discovery call with Acme",
  "body": "Discussed enterprise plan requirements and timeline.",
  "durationMins": 45,
  "scheduledAt": null,
  "completedAt": "2026-03-13T14:00:00.000Z",
  "contactId": "contact-abc123",
  "companyId": "company-abc123",
  "dealId": "deal-abc123",
  "isPrivate": false,
  "createdAt": "2026-03-13T10:00:00.000Z",
  "updatedAt": "2026-03-13T10:00:00.000Z"
}

HubSpot links & search

With HubSpot connected, companies and contacts are linked to tasks, boards, roadmap projects and River pages. Links are references: nothing is written to HubSpot. Each endpoint checks the module that owns the item (Projects for tasks and boards, Roadmap for projects, River for pages) and, for tasks and boards, the board-group rule — an item the key's owner can't open answers 404. Without a HubSpot connection, search and linking answer 409.

A company linked to a board is the client of every task on it; Slack channel alerts use this. While HubSpot is connected the built-in CRM is switched off, so the CRM endpoints answer403.

Fields (POST)

Link

CPQ Products

Manage your product catalog. Products represent items and services available for quoting.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/cpq/products \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "productType": "recurring",
    "unitPriceCents": 9900,
    "billingInterval": "monthly",
    "currency": "USD"
  }'

CPQ Quotes

Create and manage quotes. Quotes follow a lifecycle: draft → sent → viewed → accepted/declined/expired.

Fields

Example — Create a quote

curl -X POST https://app.ladder.fish/api/v1/cpq/quotes \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Enterprise License — Q2 2026",
    "recipientName": "Jane Smith",
    "recipientEmail": "[email protected]",
    "recipientCompany": "Acme Corp",
    "validUntil": "2026-06-30",
    "paymentTerms": "Net 30"
  }'

Example — Get a quote with line items

# GET /api/v1/cpq/quotes/{id} returns quote with line items
{
  "quote": { "id": "...", "quoteNumber": 1, "title": "...", "status": "draft", ... },
  "lineItems": [...],
  "sections": [...]
}

Example — Send a quote

Sends a branded email to the recipient with a secure magic link and an attached PDF. The recipient verifies their identity via the magic link (24hr, single-use) or email OTP to view the interactive quote. Only works on draft or approved quotes that have a recipient email.

curl -X POST https://app.ladder.fish/api/v1/cpq/quotes/{id}/send \
  -H "Authorization: Bearer fl_your_key_here"

# Response:
# { "shareToken": "abc-123", "shareUrl": "https://app.ladder.fish/q/abc-123" }
#
# Side effects:
# - Quote status → "sent", sentAt timestamp recorded
# - Branded email with PDF attachment sent to recipientEmail
# - Magic link token generated (24hr expiry, single-use)

CPQ Line Items

Manage line items on a quote. Totals are auto-calculated when items are added or updated.

Fields

Example

curl -X POST https://app.ladder.fish/api/v1/cpq/quotes/{quoteId}/line-items \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan — Annual",
    "quantity": 10,
    "unitPriceCents": 9900,
    "billingInterval": "annual",
    "taxRate": 1000
  }'

Labeler work tracking

For third-party labeling platforms. Every call runs on a team API key whose creator is an admin; the labeler is named per item by labelerEmail or labelerUserId (or a nested labeler: { email | userId }). A task that carries an externalId is unique per source (default api), so pushing the same batch again updates instead of duplicating. A labeler not yet assigned to the project is assigned by the call.

Task fields

Time and unit fields

Example

# Push a batch (idempotent on externalId)
curl -X POST https://app.ladder.fish/api/v1/labeler/tasks \
  -H "Authorization: Bearer fl_..." \
  -H "Content-Type: application/json" \
  -d '[
    { "projectId": "proj_123", "labelerEmail": "[email protected]",
      "externalId": "batch-7/item-12", "title": "Label 40 frames", "quantity": 40, "status": "done" },
    { "projectId": "proj_123", "labelerEmail": "[email protected]",
      "externalId": "batch-7/item-13", "title": "Label 40 frames", "quantity": 40 }
  ]'

# Advance one task later
curl -X PATCH https://app.ladder.fish/api/v1/labeler/tasks/TASK_ID \
  -H "Authorization: Bearer fl_..." -H "Content-Type: application/json" \
  -d '{ "status": "done", "durationSeconds": 1800 }'

Webhook events: labeler.task.created, labeler.task.updated, labeler.task.completed (fires once per transition into done). Payload: { task, previousStatus }.

River Spaces

Top-level groupings in the River wiki.

Fields

River Pages

Wiki pages, organised as a tree via parentId. Content is submitted and returned as markdown — the server converts to the editor's native format. Updating content snapshots the previous version.

Fields

Moving a page: PUT with spaceId and/or parentId (null for top level). Child pages move with it; cycles and a parent in a different space are refused.

Location

GET, POST and PUT on a single page return location — where the page lives. The list endpoint adds spaceName to each row.

Example

# Create a page from markdown
curl -X POST https://app.ladder.fish/api/v1/river/pages \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Guide",
    "spaceId": "space-id-here",
    "contentMarkdown": "## Overview\n\nStart **here**."
  }'

River References

Links between wiki pages and other Fishladder entities. Linking checks that the key's owner holds the module the entity lives in (403 otherwise — e.g. Hiring for a candidate) and that it exists in the team (404 otherwise); tasks and boards also follow the board-group rule. The entity's real title is recorded from the entity itself. Keys with no recorded creator can't link.

Fields

Canvases

Interactive HTML documents that Fishladder hosts and renders in a sandboxed frame — for diagrams whose interactivity carries the meaning, such as hover detail or expandable nodes. For a static flowchart, a Mermaid code block in a wiki page is lighter. Gated by the River module, so a viewer can read a canvas and a member can publish one.

Submit a complete, self-contained document. Inline all CSS and JavaScript and embed images as data: URIs: the page renders under a policy that blocks every outbound request, so external stylesheets, fonts, scripts and image URLs will not load. Scripts run normally.

An update replaces the whole document, so the previous one is snapshotted first — a truncated write is recoverable. Renaming does not create a version.

Fields

Presentations

AI-built PowerPoint decks assembled from your roadmap, projects, goals and feedback. Reads need any valid key; every write requires an admin key.

Building is asynchronous. Creating returns 202 with a deck that does not exist yet — poll the detail endpoint until status reaches complete or failed. Limited to 10 builds an hour per team, 2 concurrent. Slides are PowerPoint and therefore static; for an interactive diagram publish a canvas and link to it.

Fields

Slide fields

AI

AI endpoints for triggering behaviors, reviewing actions, and managing settings. All v1 endpoints accept Bearer token authentication (API key), making them accessible from the CLI.

CLI-friendly endpoints (v1)

These use API key auth and are designed for CLI and programmatic use.

CRM AI

AI-powered CRM features for deal scoring, action suggestions, pipeline analysis, and data enrichment.

Examples

# Chat with AI from CLI
curl -N -X POST https://app.ladder.fish/api/v1/ai/chat \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What tasks are blocked this week?" }'

# Generate tasks from meeting notes
curl -X POST https://app.ladder.fish/api/v1/ai/generate-tasks \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj-abc123",
    "transcript": "We need to fix the login bug, update the docs, and add CSV export..."
  }'

# Suggest priority for a task
curl -X POST https://app.ladder.fish/api/v1/ai/suggest-priority \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task-xyz" }'

# Approve a pending AI action
curl -X POST https://app.ladder.fish/api/v1/ai/actions/action-id-here \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "action": "approve" }'

Session-authenticated endpoints

These use cookie session auth and are used by the Fishladder web UI.

Settings fields

Rate limits

AI endpoints have their own rate limits: Chat is 60 requests/hour, feedback ingestion is 20 requests/hour. Other AI endpoints follow standard rate limits.

Webhooks

Subscribe to real-time event notifications. See the Integrations Guide for setup details and example payloads.

Subscribe fields

Example

curl -X POST https://app.ladder.fish/api/v1/webhooks \
  -H "Authorization: Bearer fl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123/abc/",
    "events": ["task.created", "task.completed"]
  }'

Polling

Polling endpoints return recent items sorted newest-first. Use the optional since query param (ISO date) to only fetch items created/updated after a given time.

Example

curl "https://app.ladder.fish/api/v1/poll/tasks?since=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer fl_your_key_here"

Trust & Safety — Questionnaires

GET /api/trust-safety/questionnaires

List all questionnaires for the team.

POST /api/trust-safety/questionnaires

Create a new questionnaire. Requires admin role.

GET /api/trust-safety/questionnaires/[id]

Get a single questionnaire by ID.

PUT /api/trust-safety/questionnaires/[id]

Update a questionnaire. Requires admin role.

DELETE /api/trust-safety/questionnaires/[id]

Delete a questionnaire and all its questions. Requires admin role.

POST /api/trust-safety/questionnaires/duplicate

Duplicate a questionnaire for a different company. Questions are copied without answers.

POST /api/trust-safety/questionnaires/from-template

Create a questionnaire from a template (e.g. SIG Lite) with auto-fill from Drata and previous answers.

Trust & Safety — Questions

GET /api/trust-safety/questions?questionnaireId=...

List questions for a questionnaire.

POST /api/trust-safety/questions

Create a question. Requires admin role.

PUT /api/trust-safety/questions/[id]

Update a question (answer, status, assignment, etc). Requires admin role.

DELETE /api/trust-safety/questions/[id]

Delete a question. Requires admin role.

Trust & Safety — Files

GET /api/trust-safety/files?questionId=...

List file attachments for a question.

POST /api/trust-safety/files

Upload a file attachment to a question (multipart form data, max 10MB).

DELETE /api/trust-safety/files?fileId=...

Delete a file attachment. Requires admin role.

GET /api/trust-safety/files/download?fileId=...

Get a presigned download URL for a file.

GET /api/trust-safety/company-files?company=...

List files attached to a company (not a specific questionnaire).

POST /api/trust-safety/company-files

Upload a file to a company. Multipart form data with file and company.

Trust & Safety — AI

POST /api/ai/trust-safety/auto-complete

Run AI auto-complete on all pending questions in a questionnaire. Requires admin role. Rate limited: 20/hour.

POST /api/ai/trust-safety/question-chat

Chat with AI about a specific question. Supports conversation history. Rate limited: 60 AI chats per hour per team, separately from the read and write budgets.

POST /api/ai/trust-safety/suggest-assignment

AI suggests a team member to assign a question to. Requires admin role.

Trust & Safety — Other

GET /api/trust-safety/hydrate

Bulk load all questionnaires and questions for the team (used by the frontend store).

GET /api/trust-safety/activity?questionnaireId=...

Get the activity log for a questionnaire (answer changes, status changes, assignments).

GET /api/trust-safety/comments?questionId=...

List comments on a question.

POST /api/trust-safety/comments

Add a comment to a question.

GET /api/trust-safety/ai-settings

Get AI settings for the team (enabled toggles, Drive folder).

PUT /api/trust-safety/ai-settings

Update AI settings. Requires admin role.

Related guides

• CLI Tool — Getting started with the fish CLI and common workflows. Every command is listed in the CLI reference.