Open app
Sign inStart free

REST API

Six endpoints over your account, with a live request builder for each.

The REST API exposes an account's retained activity, library, tool catalogue, usage and connected clients as JSON. Its base URL is:

text
https://omniio.dev/api/v1

The API publishes six endpoint shapes and one write: the enabled switch on a server that needs no credential. OAuth, bearer credentials, client revocation and secret issuance stay behind a signed-in session.

Authentication#

Create a named key under Settings → API keys. It starts with omn_, is shown once, and is stored as a SHA-256 digest. An account may hold up to ten live keys; revocation takes effect on the next request while the retired row remains visible for review.

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

Every successful request updates that key's last used time.

The OAuth token held by an MCP client is not accepted. It is resource-bound to https://mcp.omniio.dev; accepting it at /api/v1 would break that audience boundary. An API key cannot call the MCP endpoint either.

Rate limits and CORS#

REST requests are counted in a fixed clock-minute window per API key. The published ceilings are 120/min on Free, 300 on Pro, 600 on Scale and 1,200 on Business; Enterprise is negotiated. REST reads are not MCP calls and are not billed as such.

Every metered response includes:

X-RateLimit-Limitinteger
Requests this key may make in the minute.
X-RateLimit-Remaininginteger
Requests left, floored at zero.
X-RateLimit-ResetUnix seconds
The start of the next clock-minute window.
Retry-Afterseconds · 429 only
How long to wait before repeating the request.

Browser access allows any origin, the documented methods, and the Authorization and Content-Type headers. Credentials mode is not enabled: no page can borrow an Omniio session cookie. Preflight responses may be cached for 600 seconds.

Errors#

Every failure is JSON with a stable code and a human-readable message:

json
{
  "error": "invalid_request",
  "message": "\"limit\" must be a whole number between 1 and 200."
}
CodeHTTPMeaning
unauthorized401Missing, malformed, invalid or revoked API key.
invalid_request400, 409A parameter or body is invalid, or the requested state conflicts with the resource.
not_found404No resource with that identifier exists in this account.
rate_limited429This key spent its minute; obey Retry-After.
method_not_allowed405The verb is not published; Allow lists the accepted methods.
server_error500Omniio failed unexpectedly; retry safely and report a persistent failure with its time.

Numeric parameters outside their published range are refused, not silently clamped.

Activity#

GET/activity

Returns retained run_tool audit rows newest first.

limitinteger · 1–200 · default 50
Rows in this page.
cursorISO 8601
The previous response's `nextCursor`; exclusive.
clientstring
Only rows attributed to this client ID.

The response contains data, nextCursor, and retentionDays. Each call includes id, createdAt, client and server identity, qualifiedName, ok, durationMs, error, stored arguments and result, redacted, and injectionFindings.

Pagination uses the row timestamp rather than an offset so new calls arriving while an export runs do not shift rows between pages.

bash
curl -H "Authorization: Bearer omn_…" \
  "https://omniio.dev/api/v1/activity?limit=50"
Try it nowSend a real request to this endpoint.
Held only in memory and shared between explorers on this page.
GET /api/v1/activity
Copy as curl
curl -X GET 'https://omniio.dev/api/v1/activity' \
  -H 'Authorization: Bearer '"$OMNIIO_API_KEY"

Servers#

GET/servers

Returns the complete library as this account sees it, with catalogue defaults already resolved.

statusenabled | pending | disabled
Optional status filter.
categorystring
Optional catalogue category; use a value returned on a server.

There is no pagination. Each row contains slug, name, description, category, resolved status, authType, upstream endpoint, toolCount, lastAttemptAt, lastError, and owned.

Try it nowSend a real request to this endpoint.
Held only in memory and shared between explorers on this page.
GET /api/v1/servers
Copy as curl
curl -X GET 'https://omniio.dev/api/v1/servers' \
  -H 'Authorization: Bearer '"$OMNIIO_API_KEY"

GETPATCH/servers/{slug}

GET returns that same server shape. PATCH accepts exactly one field:

json
{"enabled": true}

Only servers with authType: "none" can be switched through the API. A server requiring OAuth or a bearer token answers 409 because connecting a credential is a signed-in app action. Enabling starts a catalogue warm-up and returns the fresh resolved server.

Try it nowSend a real request to this endpoint.
Held only in memory and shared between explorers on this page.
GET /api/v1/servers/
Copy as curl
curl -X GET 'https://omniio.dev/api/v1/servers/' \
  -H 'Authorization: Bearer '"$OMNIIO_API_KEY"

Tools#

GET/tools

Returns the qualified tool names currently available from enabled servers.

serverstring
Optional server-slug filter.
limitinteger · 1–500 · default 100
Tools in this page.
offsetinteger · 0–100,000
How many matching tools to skip.
schemaboolean · default false
Set to true to include each full input JSON Schema.

The response contains data, total, and nextOffset. A tool carries qualifiedName, unqualified name, server identity, title, description, and inputSchema only when requested. The catalogue answers from cache and refreshes stale servers after the response.

Try it nowSend a real request to this endpoint.
Held only in memory and shared between explorers on this page.
GET /api/v1/tools
Copy as curl
curl -X GET 'https://omniio.dev/api/v1/tools' \
  -H 'Authorization: Bearer '"$OMNIIO_API_KEY"

Usage#

GET/usage

Returns the UTC month, call count, reset time, team name where the allowance is pooled, and the complete plan limits used by enforcement.

The plan object includes id, name, includedCalls, hardLimit, overageEurPer1k, burstPerMinute, apiPerMinute, and auditRetentionDays. blocked is true only when a hard-limited plan has spent its included calls.

Try it nowSend a real request to this endpoint.
Held only in memory and shared between explorers on this page.
GET /api/v1/usage
Copy as curl
curl -X GET 'https://omniio.dev/api/v1/usage' \
  -H 'Authorization: Bearer '"$OMNIIO_API_KEY"

Clients#

GET/clients

Returns authorized, seen and revoked MCP connections.

activetrue | false
Optional filter for live versus revoked connections.

Each row includes client ID, chosen label, registered name, active status, authorization and activity timestamps, retained attributed call count, and last call time. The response also states total and the retention window behind its call counts. Client revocation remains a signed-in app action.

Try it nowSend a real request to this endpoint.
Held only in memory and shared between explorers on this page.
GET /api/v1/clients
Copy as curl
curl -X GET 'https://omniio.dev/api/v1/clients' \
  -H 'Authorization: Bearer '"$OMNIIO_API_KEY"

Next: TypeScript SDK.

On this page