OMNIA Agents Quickstart

1. Sign in to My agents

Open Start here and sign in with the access key OMNIA gave you; you land on My agents. There you can see what your agents did, run them, add new ones from the catalog, and rate results. Ratings matter: they are how your agents learn what good looks like for you.

2. Run an agent from your code

List your agents, start a run and wait for the result:

curl -s ORIGIN/v1/platform/agents -H "Authorization: Bearer $OMNIA_KEY"

curl -s -X POST "ORIGIN/v1/platform/agents/AGENT_ID/runs?wait=1" \
  -H "Authorization: Bearer $OMNIA_KEY" -H "Content-Type: application/json" \
  -d '{"inputs":{"url":"https://example.com/pricing"}}'

Without ?wait=1 the call returns at once with a poll address; read it until status is succeeded or failed. Every finished run has its cost and a receipt hash.

Rate a run

curl -s -X POST ORIGIN/v1/platform/runs/RUN_ID/feedback \
  -H "Authorization: Bearer $OMNIA_KEY" -H "Content-Type: application/json" \
  -d '{"rating":"down","note":"Missed the annual plan price","expected":"Annual: $99/yr"}'

3. Use your agents from Claude, Cursor or any MCP client

Each of your agents is a tool on OMNIA's hosted MCP server. For Claude Code:

claude mcp add --transport http omnia ORIGIN/v1/platform/mcp \
  --header "Authorization: Bearer $OMNIA_KEY"

Other clients use the same URL with the key as a Bearer token. Tools: one run_… tool per active agent, plus list_agents, recent_runs, get_run, rate_run and usage.

4. Start an agent from another app (trigger)

If your agent has a trigger, OMNIA gives you its trigger secret once. Other apps start the agent by POSTing JSON; the body is available to the agent as {{trigger.body}}. The simplest form puts the secret in a header:

curl -s -X POST ORIGIN/v1/platform/triggers/AGENT_ID \
  -H "X-Omnia-Trigger-Token: $TRIGGER_SECRET" -H "Content-Type: application/json" \
  -d '{"lead":{"name":"Dana","company":"Acme"}}'

Or sign the request instead of sending the secret: header X-Omnia-Signature: t=UNIX_SECONDS,v1=HEX, where HEX is HMAC-SHA256 of t + "." + raw_body with the trigger secret. Signatures older than 5 minutes are refused.

5. Receive results (webhook)

If your agent has a webhook address, every finished run is POSTed there as JSON (event: "agent.run.completed", with the run's status, output, error and cost), retried up to three times. Check it came from OMNIA with the webhook secret you were given:

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
function fromOmnia(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
// header: req.headers['x-omnia-signature']

6. Let an agent use your other services

Agents can call your systems' APIs with your keys without ever showing them. Store a key once under a name (capital letters, digits, underscores); agents refer to it by name and OMNIA adds it to the request. It is encrypted at rest and never returned.

curl -s -X POST ORIGIN/v1/platform/secrets \
  -H "Authorization: Bearer $OMNIA_KEY" -H "Content-Type: application/json" \
  -d '{"name":"CRM_API_KEY","value":"..."}'

7. Tell OMNIA what happened (outcomes)

Agents get better when they learn what actually happened next: a lead that closed, an invoice paid, a booking kept. Ask OMNIA for a key with the Learning dataset scope (it can only send records) and report outcomes as they happen:

curl -s -X POST ORIGIN/v1/dataset/records \
  -H "Authorization: Bearer $OMNIA_DATASET_KEY" -H "Content-Type: application/json" \
  -d '{"source":"crm","records":[{"kind":"client-outcome","key":"deal-1042","outcomeType":"deal.closed","value":4800,"label":"Acme renewal"}]}'

Each record needs a kind and that kind's fields; GET /v1/dataset/kinds lists them. Give every record a stable key so retries never count twice. Records are stamped with your account and source; invalid ones are set aside with the reason and reported back.

8. Measure whether OMNIA helped

Choose one task and agree the metric, unit, direction and matched cases before starting. Report both the current-process result and OMNIA's result for each case. Use opaque case IDs; keep names, documents and notes out of structured fields.

curl -s -X POST ORIGIN/v1/dataset/records \
  -H "Authorization: Bearer $OMNIA_DATASET_KEY" -H "Content-Type: application/json" \
  -d '{"source":"pilot","records":[
    {"kind":"pilot-measurement","key":"case-001-baseline","pilotId":"research-quality-pilot","caseId":"case-001","metric":"review time","unit":"minutes","direction":"lower","variant":"baseline","value":30,"observedAt":"2026-10-05T12:00:00Z","synthetic":true},
    {"kind":"pilot-measurement","key":"case-001-omnia","pilotId":"research-quality-pilot","caseId":"case-001","metric":"review time","unit":"minutes","direction":"lower","variant":"omnia","value":20,"observedAt":"2026-10-05T13:00:00Z","synthetic":true}
  ]}'

These example values are synthetic and excluded from real pilot comparisons. For an actual pilot, send measured values and times with synthetic: false. Use a separate metric for quality and cost, so saving time cannot hide worse results. The owner Console calculates paired differences and saves the calculation with links to its source records. Missing and duplicate pairs are reported, never guessed.

Numeric sensor or service data uses kind: observation, with signal, numeric value, unit, opaque subject and an ISO observedAt. OMNIA creates searchable, calculated signal profiles every five minutes. Sampling cadence is not a claim about a physical vibration frequency.

9. Stream and search your growing dataset

Your agent key can search your account's structured signals and calculated profiles, including indexed archives. Dataset-only keys stay write-only. Private text is not indexed.

curl -s 'ORIGIN/v1/platform/dataset/search?q=fuel' \
  -H "Authorization: Bearer $OMNIA_KEY"

curl -s 'ORIGIN/v1/platform/dataset/records/RECORD_ID' \
  -H "Authorization: Bearer $OMNIA_KEY"

Archived search hits are compact summaries. Opening one verifies the original segment before returning the record. Unavailable or corrupt archives return an error. Search coverage reports older archive segments still awaiting indexing.

For continuous sensor readings, application events or structured media measurements, use NDJSON: one record per line. Non-null JSON values use kind: observation and a descriptive signal. Binary files use the existing file-upload endpoints; this transport carries their structured measurements and references.

curl -s -X POST 'ORIGIN/v1/dataset/stream?source=sensor' \
  -H "Authorization: Bearer $OMNIA_DATASET_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @observations.ndjson

curl -s -X POST ORIGIN/v1/platform/dataset/records/batch \
  -H "Authorization: Bearer $OMNIA_KEY" -H "Content-Type: application/json" \
  -d '{"ids":["RECORD_ID"]}'

GET /v1/dataset/capabilities reports current limits. Streaming accepts up to 25 MiB, 10,000 records and 128 KiB per line. It commits in batches of 128 so other requests can continue. Up to two streams per account and four per process are admitted; busy requests return HTTP 429 and a retry delay.

A failed request can have committed earlier batches. Its receipt includes lastCommittedLine, accepted and duplicate counts, and rejected line numbers. If the connection drops, the receipt may be unavailable. Replay the same records with the same source and stable keys to resume without double-counting. Keys identify a record and must be at most 200 characters; use a new key for a corrected observation.

// Node.js: the SDK accepts arrays or async generators.
const receipt = await client.uploadDataset(observations, {
  source: 'sensor', batchSize: 128,
  onProgress: progress => console.log(progress.processed)
});
const matches = await client.searchDataset({q: 'temperature'});
const sources = await client.readDataset(matches.recordIds);

The SDK retries replayable dataset batches with a bounded delay; it does not automatically retry model calls or other actions. Agent workflows can connect dataset-search to dataset-read, then process the original records through OMNIA. Account scope comes from the key. Calculated profiles retain source lineage and do not count as additional independent evidence.

10. Plans, limits and your data