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.

A valid key is paused if its owner has not accepted the current Terms of Service. The API returns 403 before the endpoint runs. The owner signs in to Runnit, accepts the current version once, then retries with the same key.

The same public functionality is available to user-generated MCP connections. Runnit treats REST and MCP parity as a release requirement: API and product updates must preserve the same validation, permissions, organisation scope, side effects, and failure behaviour on both surfaces. See MCP Tools.

Demo, sandbox, and training datasets keep the same API validation and permissions, but don’t send email. Operations such as staff invitations still complete and report emailSent: false so REST and MCP clients don’t claim that mail was delivered.

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 (creation can name a draft-category entry workflow stage), get a project and its details, a unified PATCH /:id update (name, description, summary, status, job number, dates, budget and currency, client, colour, tags), archive and unarchive, cascading delete, the project history feed, milestones CRUD, atomic task creation with dependency validation and scheduling (plus task dates, estimate, allocations, dependency, and assignee sub-routes), assignee options, and custom table columns (CRUD, overrides, task values, AI fill, background refresh with live fill status, and a draft preview).
/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), self-service profile picture upload and deletion, 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, /api/v1/blocked-dates	Scheduling API	The schedule calendar across users and projects, organisation closure dates, and per-user blocked-out dates (for example, syncing leave from an HR system).
/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, self-serve signup, and authentication endpoints, impersonation, API key management itself (a key cannot create or revoke keys), MCP session minting, and administrative environment tooling. Self-serve signup lives on its own signup host, outside every organisation workspace, so no workspace credential can reach it.

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, jobNumber, startDate, targetCompletionDate, budget, budgetCurrency, clientOrganizationId, color, and tags. Archiving is a separate permission-gated operation (POST /api/v1/projects/:id/archive), and archived projects reject writes until they’re unarchived. See the Projects API.

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. MCP provides dedicated tools for common workflows and call_public_api for every other documented /api/v1 operation. Tokens generated from Agent Connectivity can also use this bridge from an MCP client, but they cannot authenticate the REST API directly. See Complete REST API coverage.