CONNECT YOUR SYSTEMS

Your office, connected.

A versioned, read-mostly API: add tasks, notes and calendar events, and read your customers, pipeline stages and invoices.

Download OpenAPI 3.1 specification (v1.1.0)

1. Create a key for each system

Open Settings → Connections & API keys, then API keys (workspace owners and admins only). Name the system, tick only the permissions it needs, and choose an expiry of 30 days, 90 days or 1 year. Copy the key when it is shown; it cannot be displayed again. A key only reaches the workspace it was created in, and a workspace can have up to 20 active keys.

2. Authenticate server-to-server

Send the key as a Bearer token. Set OMNIFORGE_BASE_URL to the address of your OmniForge installation (the origin you sign in at) and call it over HTTPS from your server. Browser cross-origin calls are not enabled.

curl "$OMNIFORGE_BASE_URL/api/v1/customers?limit=20" \
  -H "Authorization: Bearer $OMNIFORGE_API_KEY"

3. Create a task

Generate a new UUID for each new record and reuse it if you retry. Creating a task puts it on the Tasks page; it does not start AI work or send anything.

curl "$OMNIFORGE_BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer $OMNIFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"title":"Follow up on new inquiry","description":"Review the customer request in our CRM.","priority":"normal"}'

A successful create returns 201 with {"id":"…","resource":"tasks"}. Repeating the request with the same key and identical input returns the same ID (200). The same key with different input returns 409.

Available endpoints

Path	What it holds	Create	Permission
`/api/v1/tasks`	Tasks for your team or yourself	Yes	`tasks:read / tasks:write`
`/api/v1/notes`	Private internal notes	Yes	`notes:read / notes:write`
`/api/v1/calendar`	Internal calendar events	Yes	`calendar:read / calendar:write`
`/api/v1/customers`	Customers with pipeline stage	No	`customers:read`
`/api/v1/invoices`	Live Stripe invoices	No	`invoices:read`

GET returns {data: [...], nextCursor: string | null}. Pass nextCursor as after for the next page. Pages default to 50 records, maximum 100, ordered by ID (not by date). Use ?id=RECORD_ID to fetch one record as {data: {...}}.

Task fields include title, description, assignee, priority, due, status and evidence; checklist is a stored JSON string. Note fields: title, content, task. Calendar fields: title, start, end, status, details, task.

Customers return id, name, contact (email or phone), channel, stage, last_contact and updated_at. Stage is the same one the Customers page shows: new (New lead), contacted, meeting (Meeting booked), quote (Quote sent), won (Customer) or lost. It follows real activity, and an owner can move someone further along or to Lost. last_contact is the latest call, chat, text or web inquiry, or null. One person can have more than one record (one per way they reached you); stage matches across them.

Invoices return id, number, customer_name, customer_email, amount (in cents), currency, status (open, paid, void, uncollectible, failed, or briefly creating), due_date, sent_at, paid_at, created_at and updated_at. Only live invoices are returned; test-mode invoices never appear. Payment status is read from Stripe about once an hour.

Scheduling and linked records

Calendar timestamps must be UTC ISO 8601 ending in Z, and end must follow start. A confirmed event cannot overlap another confirmed event (409); tentative events may overlap. API events do not create customer bookings, video meetings or invitations. Notes and events may link to an existing task by its ID.

Limits and errors

60 requests per minute per key and 300 per workspace. On 429, wait the Retry-After seconds (60). Errors are JSON {"error": "message"}: 400 invalid input or unknown field, 401 missing, invalid, expired or revoked key, 403 missing permission, 404 unknown record or linked task, 405 create on a read-only resource (customers, invoices), 409 conflict, 413 body too large.

What the API does not do

Keys cannot send email or texts, run AI employees, approve drafts, charge customers, change billing, create other keys or reach super-admin functions.

Rotate or revoke a key

Create a replacement key, update your system, confirm a successful request, then revoke the old key. Revocation blocks new requests immediately; a request already running may finish.

Visit the help center →