Getting started

What this API does

The /api/v1/* REST API lets external clients (mobile apps, scripts, server-to-server integrations) read and mutate the same data the web app uses — projects, workspaces, tasks, subtasks, time entries — without going through the browser session.

Authentication is per-organization API keys. Every request operates only on that organization's data.

Quick start

Generate a key

Open Organization Settings → API Keys → Create Key. Copy the secret immediately — it is only displayed once. Keys are prefixed with ba_.

Make a call

curl -H "Authorization: Bearer ba_..." \
     https://app.gipo.io/api/v1/workspaces

Successful list responses are shaped { "data": [ ... ], "total": <n> } (offset paging) or { "data": [ ... ], "pagination": { "nextCursor": <id|null> } } (cursor paging). Single-resource responses are { "data": { ... } }.

Browse the spec

The full OpenAPI 3.1 contract is available at /api/v1/openapi.json. The in-app API Explorer at Settings → API Keys → Open the API Explorer renders it with a live try-it-out panel.

Import into Postman

A ready-to-use Postman collection — every endpoint, plus scripts that auto-generate Idempotency-Key headers and capture created resource ids into variables — is served at /api/v1/postman.json.

In Postman, choose Import → Link, paste https://app.gipo.io/api/v1/postman.json, and import. The collection arrives with its base_url already pointed at your domain — just open the Variables tab and set api_key to your ba_… key.

What you can do

Authentication

Send your key, key lifecycle, and security best practices.

Idempotency

Safely retry POST requests with the Idempotency-Key header.

Pagination

Offset and cursor pagination conventions.

Rate limits

How many requests per minute and at once you get, and how to back off.

Errors

Status codes, error envelope, and validation details.

Resources

Resource	What it does
Projects	Full CRUD over projects and project members.
Workspaces	Read workspace boards and stages.
Tasks	Create, update, move, and finalize tasks.
Subtasks	Manage subtasks nested under a parent task.
Time entries	Log and adjust manual time entries.
Members, Task types, Tags	Read-only registries.

Conventions at a glance

Base URL — https://app.gipo.io/api/v1.
Auth header — Authorization: Bearer ba_<key>.
Postman — Import → Link → https://app.gipo.io/api/v1/postman.json.
OpenAPI — https://app.gipo.io/api/v1/openapi.json.
Mutations — JSON bodies with Content-Type: application/json.
Multi-tenant — Every endpoint filters by the key's organization; cross-org IDs return 404.
Dates — ISO-8601 timestamps in UTC (YYYY-MM-DDTHH:mm:ss.sssZ).
Rate limit — 300 requests per minute and 3 requests in flight at once per organization; over either, 429 with Retry-After.

Not in the API

A few in-app endpoints exist outside /api/v1/ and use the browser session cookie instead of API keys (chat, search, HTML report download). These are intentionally not part of the public API contract.