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.

For a new workspace, first accept your invitation and sign in before creating credentials. Hosting deployment and initial workspace provisioning are not available through personal REST keys or MCP connections. Both use the same organisation-bound access once the workspace is ready.

Organisation notification-policy administration requires browser sign-in as an owner or admin and is not available through REST keys or MCP. Manage it in Settings > Notifications.

Master-project saves apply the details and budget valuation together. A failed save leaves the previous record unchanged. Both REST keys and MCP connections stay bound to their selected organisation, including when the connected user belongs to other organisations.

Project membership saves retain explicit zero-hour allocations and record the connected user as the author. REST and MCP apply the same team permissions and financial filtering.

The named project and milestone mutation tools and activation approval requests require an unscoped user-generated connection. Client-scoped sessions cannot preview or execute them. Ordinary generated REST keys keep the existing project operations.

Client-scoped MCP sessions use named tools instead of call_public_api. The selected client limits project and related task, member, commentary, time, cost and linked-file reads, including counts, totals and known-ID lookups. See project read scope.

Saved project views preserve personal privacy and shared-view permissions. A default change and its view save succeed or fail together through REST and MCP.

Shared tasks use one task ID and accept several assignees through REST and MCP. The estimate applies to each person, and the task keeps one shared status, discussion and schedule.

Organisation calendar settings include settings.weekStartsOn: 0 for Sunday or 1 for Monday. Authorised settings managers can update it through REST, MCP call_public_api or the named configure_workspace_basics tool; omitted settings are preserved.

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.

Project detail reads include selected project role names and staff role titles for task assignees. These labels do not change saved rates or add project membership. See Projects API for the fields and role-selection request.

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.

Asset linking reuses a file already visible on the destination, including an image Ru generated in a project conversation. REST and MCP return the existing asset without making another project copy.

OAuth-connected MCP clients have the same access through those tools. Their access tokens are intended for MCP and aren’t accepted directly by /api/v1. Approving connections and managing credentials requires browser sign-in, so those operations aren’t available through REST keys or MCP. See OAuth client configuration.

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.

Personal work and planning have separate read paths. The Tasks API excludes draft projects from the personal overview, while the Scheduling API retains tentative capacity and exposes the project and booking states.

File, task, milestone and organisation profile writes use the connected user’s identity for author attribution, including managed-client creation and profile updates. Supplying an actor ID in the request doesn’t change that identity. Retained file history limits return structured errors; see the Assets API before retrying a rejected save.

Profile and portfolio edits, and work-history reads and edits, use your key’s organisation. Being an admin or owner elsewhere does not grant access through that key. See staff profile permissions.

To renew a pending or expired team invitation without changing the person’s role or rates, use the resend invitation endpoint. The same operation is available through MCP’s call_public_api.

Purchase-order and supplier-bill approvals use cost access independently of selling-price access, including decision and cancellation replies. See the approval cost contract. Purchase approval event webhooks omit financial prose and opaque details while preserving identifiers and structured decision, status and reminder information.

Project record responses protect budget-derived calculations as well as the budget itself. Completion can be unavailable for callers without financial-report access, including in saved responses and revision conflicts. See the record response contract.

create_task, set_task_dependencies, update_task, update_task_status, create_task_comment and delete_task require an unscoped user-generated connection. Client-scoped sessions, including Internal, cannot use these actions or deletion previews. A component tool grant does not remove this restriction. Keep the session’s scope when handling a refusal. Normal task permissions still apply to unscoped connections.

See task tools.

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 tasks or projects complete, with personal task lists and contribution summaries), 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, /api/v1/work-patterns, /api/v1/calendar	Scheduling API	The schedule calendar across users and projects, organisation closure dates, per-user blocked-out dates, recurring working patterns (for example, syncing leave and a move to four days from an HR system), and read-only Google or Microsoft calendar connection health.
/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.
/api/v1/approvals	Approvals API	List approvals (waiting, assigned, requested, all), read the full detail, record idempotent decisions (approve, reject, request changes), cancel and reassign, create standalone or staged approvals, manage standing delegations, configure approval gates (auto apply, expiry behaviour, per-client overrides), receive signed external decisions, and request project activation approval.
/api/v1/finance	Finance & Budgets API	Finance status and settings, billing entities, tax rates, numbering, activity codes, expense categories, bank accounts with dual control, custom fields, budgets with sections and lines, change orders, billing schedules, work and lineage, task mapping, templates and the catalogue.

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

Finance policy refusals can share the PURCHASE_INVALID code while their message names the specific blocker. Read that explanation before retrying. Invalid fields can be returned in an errors array. Supplier payment amounts must be positive; a negative amount is not a reversal. See the Finance API.

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.

Finance returns entered budget prices separately from net sold and hourly rates. Source-based invoice drafts use prices before tax; incompatible inclusive requests are refused consistently through REST and MCP. See the Finance API for pricing fields and validation codes.

Finance forecast filters use the attributed share of mixed invoices, bills and expenses. See Forecast source filters for exclusions and weekly-total calculations.

Finance time approval and reporting use shared currency valuations across API and MCP access. See the Finance API reference for recorded values, explicit repricing and realisation coverage.

Budget used also includes approved billable purchases. Expense split totals and dated bill voids follow the shared Finance contract.

Finance cost reports include received but unbilled purchases and dated self-billing relief. Generated REST and MCP credentials receive the same recorded values and source-reservation guards. See Finance API.

Bank settlement and reimbursement corrections preserve dated history through the same permissions and validation in REST and MCP. See the Finance API reference.

Finance period checklists link to live, paginated supporting records. The Finance API reference describes source permissions, date scope and generated-token access.

Internal charge setup, providing credits and corrections use the shared Finance contract. See Internal chargebacks.

Repeated entity attachment keeps the existing linked asset. For saving a file to a specific collection through MCP, see Files and folders, including how repeated saves reuse an existing copy.

File access and workspace binding

A generated credential stays bound to its organisation. Your membership in a second workspace cannot supply missing authority for a file read, owner filter or folder change. Authorised client relationships still apply.

For demo, sandbox and training datasets, schedules include only the connected dataset and its clients. Production schedules exclude those sample projects. Browser dashboard views use the same boundary; their presentation endpoints aren’t public API resources. Read work through the task and schedule APIs. Staff profiles shared with Production are read only from a sample dataset, including your own profile, avatar and portfolio; writes return 403 through REST and MCP. See Staff Profiles & Work History. Creating, switching and seeding datasets use signed-in browser settings and are unavailable through generated REST or MCP credentials.

Direct file reads need permission to view assets. Private files have extra source restrictions, shared by the public API and ordinary user-generated MCP file readers. See Private files.

Workspace maintenance

Maintenance during workspace moves temporarily returns HTTP 503 with Retry-After: 30 for REST and MCP. Keep using your workspace hostname; cached DNS continues to work and you do not need to change endpoints or clear DNS caches. After the move, sign in again and replace or reconnect your credentials. See maintenance and authentication.

Browser sign-in and provider callbacks are outside the public API and MCP. A workspace move preserves your browser SSO sign-in method; generated API keys and MCP connections still need to be renewed after the move. See workspace maintenance and signing in after a move.

Finance document previews

Quote, purchase-order, statement and self-billing HTML previews are available through the Finance API, with the same permissions through MCP. See Reading document previews.

The Finance API also accepts receivable document uploads with automatic extraction, original-file previews, reviewed invoice imports and explicit payment confirmation. You can correct a document’s type or restore a dismissed upload for fresh review. The same actions are available through MCP with the connected user’s permissions.

Account purchase confirmations

Runnit subscription and AI-credit purchases are managed through the signed-in account settings. Personal REST keys and MCP connections cannot start these purchases, submit payment-provider callbacks or send purchase confirmations. Successful payments generate confirmation emails automatically. This does not change the Finance API for your own customer invoices and payments.

See Billing and subscriptions and AI Credits.

Owners and admins can configure optional left-menu shortcuts per active member through the member menu API. The same GET and PUT operations are available through MCP’s call_public_api. These preferences change menu presentation without changing feature access.

Enterprise owners and admins can read, replace and reset their tenant’s AI recovery policy through REST or MCP. Models, fallback order and attempt counts share the same validation and organisation binding on both surfaces.

Application activity

Owners and admins can read GET /api/v1/analytics/activity using their generated credential. Reads remain bound to its organisation; cross-tenant fleet access and browser presence submission are excluded. See the App activity API for filters, response fields and MCP examples.

Role planning

The optional task-table role column can be included in organisation or board default column settings. Its inline controls use the same task role endpoints. See table defaults and organisation settings.

Tasks can reserve rate-card roles before people are selected. Generated REST keys and MCP connections support creation, staffing, reopening and unfilled demand with the same organisation binding and permissions. See the Tasks API.

Use the manual bill matching action to link saved draft lines to issued purchase orders without changing their amounts. REST and call_public_api share the current bill hash, reviewed budget allocation and live cost-access checks. MCP writes require confirm:true.

Saved bill matching details require cost access to the bill and every referenced order. REST, call_public_api and named bill tools apply the same permissions to retained history and lists.

Read saved task budget mappings

Task details, personal task lists and project task records include the saved budgetLineId, or null when unmapped. Use the Finance mapping endpoints to change it. The same reads and writes are available through call_public_api.

For SVG uploads, downloads and saved versions, see SVG content, including raw XML, base64 and MCP downloads that use the binary envelope when bytes cannot round-trip through UTF-8.

Asset ZIP downloads accept a collection ID or an entity type and ID, with the same current file access rules and optional collection-owner scope for organisation entities.

JSON and form-encoded request bodies have a 20 MiB limit. Oversized requests return 413 with PAYLOAD_TOO_LARGE and details.limitBytes; reduce the payload before retrying. File encoding counts towards the limit. See Assets API upload limits.

Asset mutations require live upload permission in the authorised organisation, including file versions and destination collection creation. Reads keep separate permissions. See Assets API permissions.

Ordinary credit amounts follow the original invoice’s tax-inclusive or tax-exclusive entry mode. Inclusive credits cannot exceed either the remaining before-tax amount or total, including other credit drafts. Retention-release credit notes keep their recorded tax amounts and return only the credited share to retention. REST and MCP use the same rules. See the Finance API.

Purchasing document permissions use each bill’s project and current client, and each order’s recorded project and client. This includes document lists and the named raise_po, draft_supplier_bill and list_supplier_bills results. Manual attachment and matching writes refuse changed bill scopes before saving; repeated mappings still check selected-order cost access.

Creating a purchase order link requires both order management and cost access for its recorded project/client. Refused requests create no document or link. Existing supplier links retain their separate authority.

Purchase order revisions that fall below received or on-charged quantities return 409 with PO_REVISION_BELOW_CONSUMED. The generic error omits the consumed quantity and leaves the order unchanged.

Purchase order and bill costs are available with the document’s cost access without also granting selling-price access. Selling totals need prices; markups need both. Named purchase tools and call_public_api return the same permitted values. Bill payment history checks cost access to every contributing bill before showing a whole-payment total. See Finance API for allocation and unallocated-payment visibility.

Purchasing totals require cost access to every contributing order and bill. Restricted supplier spend and linked bill figures are omitted; complete ageing and accrual reports refuse incomplete access. The payment picker lists only readable bills. Named get_supplier applies the same spend rule. See Purchasing aggregate permissions.

Closing a Finance period saves its purchase accrual balances as part of the same close operation. A repeat close preserves them; a new close after reopening replaces them. Cost access is still checked when you read the figures. See period close.

Complete month-end reports, report history and CSV/PDF exports require unrestricted organisation-wide price and cost access. A project or client restriction returns 403 even if that scope is outside the selected period. Exports also require finance:export. These rules apply to REST and call_public_api; period-closing permission is unchanged. See month-end reports.

get_profitability honours project/client financial grants when you name the subject. It returns the same permitted metric cells as the public metrics API, including cost-only amounts. Client-bound sessions stay within their client; job-bound sessions cannot use this report. See scoped profitability for the result and validation contract.

Supplier-uploaded invoice originals and proposals follow current cost access to all linked purchase records, or organisation cost access when unattached. Linked acceptance needs readable source costs. Named file readers, discovery and the public API bridge preserve these restrictions. See Supplier invoice originals and Supplier upload cost scope.

Live month-end figures

The live month-end brief requires unrestricted organisation-wide prices, with no project or client price denies. Costs are not required for this sales/WIP brief. Period checklists still return counts and status under their read permissions, but omit current and saved amounts without complete price access. The same rule applies to period action responses, audit history and MCP reads. See Finance API.

Supplier-payment recording and reversal keep action permission separate from amount visibility. Response totals need all contributing bill cost scopes; recording also checks selected bills that receive no allocation. Remainders need organisation cost access. Authorised writes can succeed with payment identity and hidden amounts. See supplier payment visibility.

Named record tools accept your generated connection. Client-scoped record reads remain within the selected active client; Internal scope selects projects without a client. Form definitions and record changes require an unscoped connection. See project record tools.

Project record endpoints bind each read and lifecycle action to your key’s organisation, even if you also belong to the project’s organisation. The same boundary applies through call_public_api. See Project Records API.

Saved journal corrections

Journal lists and exports return the same signed correction totals through REST and call_public_api, with the same permissions. A correction reverses journal movement while keeping recorded period facts. Neither transport provides a correction-creation action.

Project dates and budget figures

Project calendar dates and budget figures retain the same values through REST and MCP. The browser’s date formatting and small-margin display do not alter the returned dates, basis points, lifecycle or financial permissions.

Supplier spend currencies

Supplier summaries keep each bill currency separate. Read spendYearByCurrency and preserve its labels; mixed currencies have no combined spendYear value. See supplier spend for the shared public API and named MCP contract.