The REST API.

Overview

Every endpoint is under https://omniio.dev/api/v1, takes and returns application/json, and is scoped to the account the key belongs to. There is no account or workspace id in any path — the key is the scope.

The API is deliberately narrow. Five resources are readable and exactly one field is writable, because the things worth doing from a script are reporting and deployment checks, and the things that hand Omniio a credential belong behind a session where a person can see what they are connecting.

GET /activity

Tool calls, newest first, as far back as your retention reaches.

GET /servers

Your library, with each server's real resolved status.

GET · PATCH /servers/{slug}

One server, and the one thing about it a program may change.

GET /tools

Every qualified tool name your endpoint currently answers.

GET /usage

This month's calls, the plan behind them, and when the counter rolls.

GET /clients

Clients holding a credential for this account, and ones that ever called.

Authentication

One header. Keys are created at settings → API keys, shown once, and stored as a SHA-256 digest — we cannot show you an existing key, only issue another.

curl -H "Authorization: Bearer omn_…" \
  "https://omniio.dev/api/v1/usage"

Authorizationrequired

Bearer omn_…. A missing or unparseable header answers 401 with WWW-Authenticate: Bearer.

Content-Typewrites only

application/json on PATCH. Reads take no body.

Every request stamps its key’s last used time, so a key nothing has touched in months is visible as such on the settings screen. Revoking one takes effect on the next request.

Rate limits

Counted per key, per minute, in a fixed window aligned to the clock. Every plan’s ceiling:

Free

120 requests a minute per key · audit retention 7 days

Pro

300 requests a minute per key · audit retention 30 days

Scale

600 requests a minute per key · audit retention 3 months

Business

1,200 requests a minute per key · audit retention 6 months

Enterprise

Negotiated. No counter runs and no rate-limit headers are sent.

Every metered response carries where you stand:

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1760000040

X-RateLimit-Limitinteger

Requests this key may make in a window.

X-RateLimit-Remaininginteger

How many are left in the current one. Floors at zero rather than going negative.

X-RateLimit-Resetinteger

When the window rolls, as seconds since the Unix epoch — the same convention GitHub and Stripe use, so existing back-off code reads it without a special case.

Retry-Afterinteger

Seconds to wait. Sent only with a 429.

Over the line, the answer is 429 with the wait in both a header and the body:

{
  "error": "rate_limited",
  "message": "Rate limit reached: the Pro plan serves 300 API requests per minute per key, and this key has spent this minute's. Retry after 12 seconds. This limit is per key and separate from your MCP burst limit — your agents are unaffected, and nothing was billed. Raise it at https://omniio.dev/pricing.",
  "retryAfter": 12
}

Errors

Every failure has the same shape: a stable error code to branch on and a message written for whoever has to work out why the nightly sync stopped. The HTTP status agrees with the code; neither is ever the only signal.

{
  "error": "invalid_request",
  "message": "\"limit\" must be a whole number between 1 and 200."
}

unauthorized401

No bearer credential, or one that is not a live Omniio key. Revoked keys answer this too.

invalid_request400 · 409

A parameter or body field is wrong (400), or the change asked for conflicts with the state of the thing (409). The message names the field.

not_found404

No such resource on this account. Slugs are checked against your library, so a server you have not added reads as missing rather than forbidden.

rate_limited429

This key has spent its minute. Wait the number of seconds in Retry-After and repeat the request unchanged.

method_not_allowed405

The endpoint does not answer that verb. The Allow header lists the ones it does.

server_error500

Something broke on our side. Safe to retry; if it persists, tell us and quote the time.

429 is the only status worth retrying automatically, and only after the wait it names. Retrying a 400 unchanged will fail identically.

Pagination

Two schemes, because two different kinds of set are being walked.

Cursors, for the audit trail

/activity returns nextCursor: pass it back as ?cursor= for the next page, and stop when it is null. The cursor is the timestamp of the oldest row you were given, so new calls arriving mid-walk cannot shift rows into a page you have already read — which is exactly what an offset would do on a table that grows while you page through it.

Offsets, for the registry

/tools returns nextOffset and total. This set is small, finite and not appended to while you read it, so an offset is honest here and simpler to resume.

Neither, for the short lists

/servers and /clients return everything with a total beside it. Both are lists in the low hundreds at most; saying so plainly beats leaving you to infer it from a missing cursor.

Servers

{
  "data": [
    {
      "slug": "github",
      "name": "GitHub",
      "description": "Repositories, issues and pull requests.",
      "category": "development",
      "status": "enabled",
      "authType": "oauth",
      "endpoint": "https://api.githubcopilot.com/mcp/",
      "toolCount": 41,
      "lastAttemptAt": "2026-01-14T09:30:58.204Z",
      "lastError": null,
      "owned": false
    }
  ],
  "total": 1
}

curl -X PATCH \
  -H "Authorization: Bearer omn_…" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  "https://omniio.dev/api/v1/servers/astro-docs"

CORS

Every endpoint answers Access-Control-Allow-Origin: * and handles OPTIONS, with a preflight cached for 10 minutes. The rate-limit headers and Retry-After are on the expose list, so a browser client can read them.

Access-Control-Allow-Credentials is deliberately absent. There is no cookie and no ambient credential in play — every request carries a bearer key explicitly — so a page that has not been given one cannot borrow anybody’s session by calling from a browser.

TypeScript client

One file, no dependencies, no build step. It runs anywhere fetch exists — Node 18+, Deno, Bun, Cloudflare Workers — and it handles the two things that are actually awkward about this API: walking a cursor to the end of the retention window, and backing off when a key’s minute is full, using the server’s own Retry-After rather than an invented curve.

It is not published to a package registry. Download it into your project and it is yours — you can read all of it in one sitting, which is more than can be said for most generated clients:

curl -O https://omniio.dev/sdk/omniio.ts

import { Omniio, OmniioError } from "./omniio";
const omniio = new Omniio({ apiKey: process.env.OMNIIO_API_KEY! });
// One page, newest first.
const page = await omniio.activity({ limit: 50 });
// Or the whole retention window, a page at a time, cursor handled for you.
for await (const call of omniio.activityAll()) {
  if (!call.ok) console.warn(call.qualifiedName, call.error);
}
try {
  await omniio.setServerEnabled("astro-docs", true);
} catch (error) {
  if (error instanceof OmniioError && error.code === "invalid_request") {
    // That server needs a credential, which is connected in the app.
  }
}

activity(params)

One page. Returns data, nextCursor and retentionDays.

activityAll(params)

An async iterator over every call, following the cursor. Yields rows rather than pages, because a busy month held in one array is how a warehouse sync runs out of memory.

servers(params)

The library, filtered by status or category.

server(slug)

One server.

setServerEnabled(slug, enabled)

The PATCH, returning the server as it now stands.

tools(params)

One page of the registry.

toolsAll(params)

An async iterator over every tool, following the offset.

usage()

This month's counts and the plan behind them.

clients(params)

Connected clients.

Failures arrive as an OmniioError carrying code, status and, on a 429, retryAfter — so your retry logic branches on the code while your logs get the sentence. Constructor options are apiKey, baseUrl, fetch and maxRetries (three by default; zero throws the rate limit straight through).

Webhooks: the same rows, pushed →