1. This video shows how your own software works with OAIZ, through the API and the CLI.
Developer

What you can build on OAIZ

The API and the CLI open OAIZ to your own software.

The appYou, in the browser
APIYour software
>_ CLIYour terminal
  1. In the app, you work with workflows, jobs, events, runs and knowledge.
  2. Your programs reach the same things. Code calls the API, and a terminal or a coding agent uses the CLI.
  3. Each program uses an account, and reaches only what that account is allowed to.

What you work with in the app

Your programs reach the same things

Each program uses an account

The appChat, Library, Activity Sam Holm
OAIZ
Workflows
Jobs
Events
Runs
Knowledge
APIYour software Service account
>_ CLIA terminal or a coding agent Sam Holm
Access follows the account
  1. Your software calls the API over HTTP, or through SDKs for TypeScript, Python and Go.
  2. Read lists what your account can see, or fetches a single item, such as one run.
  3. Change edits a draft, tests it, and publishes the work you checked.
  4. Publish sends an event from your own system, and matching live workflows react.

Your software calls the API

Three kinds of operation

https://api.oaiz.io
HTTP TypeScript SDK Python SDK Go SDK
Read

List or retrieve what your account can see.

Workflows Jobs Events Runs Knowledge
Change

Edit a draft, test saved work, and publish the checked branch.

Edit the draft Test it Publish
Publish

Send an event from your own system.

Event from your system Matching live workflows react
  1. A program signs in with an API key, which you create in Settings, under API keys.
  2. Each key belongs to a person or a service account, and uses that account's current access.
  3. It goes in the Authorization header. Keep it on your server, and out of browser code.

A program signs in with an API key

The key uses its owner's access

Send it in the Authorization header

Settings API keys Create API key
API key
NameContact form
ExpiresNo expiration date
AccountService account · Fjord shop
SH A personSam Holm. The key uses Sam's access.
A service accountFjord shop. The key uses its own grants.

A service account key does not inherit the access of the person who created it.

Request header
Authorization: Bearer <API_KEY>
On your server
Not in browser code
  1. Maya sends the contact form on Fjord Living's website, and the shop's server passes it to OAIZ.
  2. It posts to the publish address, with the API key in the header.
  3. The body is the event. Its provider is custom, and its properties carry her message.
  4. OAIZ answers that the event was created, and every live workflow with that trigger starts.
  5. If it fails, 401 means the key did not work, and 403 means the account is not allowed.

Maya's message comes from the shop

A request to the publish address

The body is the event

OAIZ answers

A failed request says why

Contact usfjordliving.com
Maya Chen
My order 4821 arrived with a cracked lamp shade.
Send
Shop serverHolds the API key
Request
curl -X POST https://api.oaiz.io/ingest/event/publish \ -H "Authorization: Bearer $OAIZ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "eventType": { "provider": "custom", "name": "customer-message" }, "properties": { "message": "My order 4821 arrived with a cracked lamp shade." }, "uniqueKey": "contact-4821" }'
Response
201 Created
customer-messageEvent created
Live workflowswith this triggerStarted
401Authentication failed
403Not allowed
  1. The CLI brings the same operations to your terminal.
  2. To build, get a workflow as a file, edit it, and save it on a new branch.
  3. Test the branch on the latest real event. By default, a test keeps integration writes off.
  4. To deploy, merge the branch into main and set it live.
  5. Apps work the same way. Pull the files, push your changes, and publish.
  6. One more command installs the OAIZ skill, so a coding agent can do this too.

The same operations in your terminal

Build on a branch

Test on a real event

Deploy by merging

Apps work the same way

Teach a coding agent

Terminal
oaiz login
oaiz workflow get "$workflow_id" --file workflow.jsonoaiz workflow edit "$workflow_id" --file workflow.json --new-branch "Reply change"
oaiz workflow run "$workflow_id" --branch "Reply change" --latest-event
oaiz workflow branch merge "Reply change" --status live
oaiz view pull <viewId> --branch mainoaiz view push --message "Add the refund table"oaiz view publish --yes
oaiz skill install
Same API
Sam Holm
Signed in through the browser, with Sam's access
Customer requests
mainLive
Reply changeNew branch
Reply change merged into main, live
Test run
Latest eventSucceeded
Integration writes off
Refund approvals
Next versionPushed
App addressPublished
Coding agent
.claude/skills/oaiz
.agents/skills/oaiz
Learns the CLI's workflow, test and data commands
  1. Use the API when your own software works with OAIZ, like a website that sends events.
  2. Use the CLI when you, a script or a coding agent build, test and deploy workflows and apps.
  3. Now you know what each one is for. The API and CLI pages in the docs go deeper.

When to use which

APIYour software works with OAIZ
A website sends events as they happen
A server reads workflows and runs
SDKs for TypeScript, Python and Go
>_CLIYou or a coding agent at work
Build, test and deploy workflows
Push and publish apps
Let a coding agent run the commands