API reference

Conventions

36 operations, all sharing one envelope, one authentication scheme and one set of rules. Learn these once and every resource page becomes a list of field names.

Base URL

text

https://gateway.octopusoperations.co.za/v1

The version is in the path. A v2 would live beside v1 rather than replacing it, so an integration that works today keeps working.

The envelope

Every response has the same outer shape, success or failure:

Success

{
  "success": true,
  "data":    { },
  "message": "Human-readable, safe to show a user.",
  "version": "v1",
  "count":   25
}

data: an object for a single record, an array for a list.
count: only on lists.
message: written for a person; safe to surface in your UI.
success: check this, not the status code, if you only check one thing.

Discovery

GET /v1 returns your organisation, your scopes and every operation with a one-line summary. It is the cheapest way to confirm a key works, and worth calling in your integration's health check.

Ids and dates

Ids are UUIDs, generated by Octopus. Never construct one.
Dates like dueDate are YYYY-MM-DD strings.
Times like startsAt are epoch milliseconds, as numbers.
Timestamps on records are ISO 8601 strings.

Filtering

Filters go in the query string, and are documented per resource. GET /v1/tasks?projectId=… narrows to one project; GET /v1/calendar?from=…&to=… takes a window.

Calendar reads are capped at 400 days

Ask for a wider window and you get a 400 explaining the limit. Page through in chunks rather than requesting a decade in one call.

Resources

Organisation1 operation

The organisation a key belongs to. One call, and it is the quickest way to confirm a key works and see which tenant it is pointed at.

Projects7 operations

Projects and their milestones. A project is the unit almost everything else hangs off: tasks, risks, issues and financial entries all reference one.

Tasks7 operations

The unit of work. Tasks belong to a project, are assigned to a person, and carry a due date. All three are required, because a task without them cannot be chased.

Calendar6 operations

Events, deadlines and reminders. Reads take a window; repeating events are returned as rules rather than as one row per occurrence.

Clients4 operations

The companies you work for. Projects, events and issues can all reference a client.

Personnel3 operations

People on the roster, and the groups they belong to. This is where you find the user ids that tasks are assigned to.

Documents2 operations

Files held against the organisation. Reading one returns a short-lived download URL rather than the bytes: the file never passes through the API.

Financials2 operations

Income and expense entries, and the totals derived from them.

Assets2 operations

Plant, equipment and vehicles, with who currently holds them.

Risks & issues2 operations

The risk register and the open issues list, rolled up across every project. Both are governed by projects.read: they are a view of project health, not a resource of their own.