REST API Overview

Runnit exposes a versioned public REST API at /api/v1, authenticated with per-user API keys. It covers the core of the product: projects, tasks, milestones, master projects, schedules, budgets and reports, rate cards, staff and work history, clients, organisations, asset collections, files, and search.

Every endpoint mirrors the in-app behaviour exactly. A request runs as the user who owns the API key, with that user’s current role, capabilities, and client assignments, so the API can never do more than the key’s owner can do in the app. See API Keys & Authentication for how to create a key and send it with requests.

Base URL

Requests go to your Runnit backend with the /api/v1 prefix, for example:

https://api.runnit.io/api/v1

If your organisation runs its own deployment, replace the host with your deployment’s API address.

Discovery endpoint

GET /api/v1/ needs no authentication and returns a discovery document that lists the supported authentication methods and the mounted resources:

curl https://api.runnit.io/api/v1/

Every other endpoint requires a valid API key.

Response envelope

Successful responses return JSON with a success flag and the resource under a named field, for example:

{ "success": true, "project": { "...": "..." } }

Failures return the HTTP status codes described in API Keys & Authentication, along with an error message in the body.

Resources

Every resource has a full endpoint-by-endpoint reference page with request fields, responses, permissions, and examples.

Resource	Reference	What it covers
/api/v1/projects	Projects API	List and create projects, get a project and its details, a unified PATCH /:id update (name, description, summary, status including archived, job number, dates, budget and currency, client, colour, tags), cascading delete, the project history feed, milestones CRUD, task creation with scheduling (plus task dates, estimate, allocations, and assignee sub-routes), and assignee options.
/api/v1/tasks	Tasks API	Your assigned tasks (GET /my), get and update a task, status updates, comments (read and add), and task deletion.
/api/v1/master-projects	Master Projects API	Master project CRUD, hierarchy, budget rollups, dependencies, and sub-project linking.
/api/v1/organizations	Organisations & Staff API	Get and update the organisation, members (list, invite, update, remove), member rate settings, and user imports (preview, commit, rollback).
/api/v1/organizations (rate cards)	Rate Cards API	Rate-card roles CRUD, client rate cards and role overrides CRUD, effective rate resolution, and project rate-card assignment.
/api/v1/organizations/:orgId/clients	Clients API	Client relationships: list, link, create, get, update, and remove, plus client teams and assignments.
/api/v1/users	Staff Profiles & Work History API	Staff profiles (get and update), portfolio and work-history entries CRUD (work history also syncs automatically when projects complete), client assignments, and organisation role.
/api/v1/reports	Reports API	Summary, budget, performance, delivery, workload, and client reports, plus export. Financial data requires the user’s financial reporting capability.
/api/v1/schedule, /api/v1/closure-dates	Scheduling API	The schedule calendar across users and projects, plus organisation closure dates.
/api/v1/collections	Asset Collections API	Asset collection CRUD and entity links.
/api/v1/assets	Assets API	Upload, download, versioned metadata and content updates, delete, folders, tags, and semantic search.
/api/v1/permissions, /api/v1/search	Permissions & Search API	Permission introspection and administration, project team management, and cross-entity search.

Not available through API keys: registration and authentication endpoints, impersonation, API key management itself (a key cannot create or revoke keys), MCP session minting, and administrative environment tooling.

Examples

Replace rnk_your_key with your API key and the placeholder IDs with real values.

List projects

curl https://api.runnit.io/api/v1/projects \
  -H 'Authorization: Bearer rnk_your_key'

Create a task in a project

curl -X POST https://api.runnit.io/api/v1/projects/<project-id>/tasks \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Draft homepage copy",
    "description": "First pass for internal review.",
    "priority": "high",
    "assignedToId": "<user-uuid>",
    "plannedStartDate": "2026-07-13",
    "estimatedHours": 6
  }'

Only name is required. priority accepts low, medium, high, or critical. When you supply an assignee, start date, and estimate, Runnit also builds the task’s schedule.

Update a project

curl -X PATCH https://api.runnit.io/api/v1/projects/<project-id> \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "active",
    "targetCompletionDate": "2026-09-30",
    "budget": 80000,
    "budgetCurrency": "AUD"
  }'

PATCH /api/v1/projects/:id accepts any subset of name, description, summary, status (including archived), jobNumber, startDate, targetCompletionDate, budget, budgetCurrency, clientOrganizationId, color, and tags.

Upload an asset

curl -X POST https://api.runnit.io/api/v1/assets \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileName": "brand-guidelines",
    "fileExtension": "pdf",
    "content": "<base64-encoded file content>",
    "collectionId": "<collection-uuid>"
  }'

Assets belong to collections; create or look up a collection through /api/v1/collections first. Send file content as text or base64 in the JSON body; see the Assets API for the full field list.

Rate limits and errors

Each key can make up to 600 requests per minute by default; requests over the limit return 429. Authentication and permission failures are described in API Keys & Authentication.

MCP parity

The same rnk_ API keys also authenticate the MCP server, so one credential can drive both the REST API and MCP tool calls from AI agents.