- 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.
APIYour software
>_
CLIYour terminal
- In the app, you work with workflows, jobs, events, runs and knowledge.
- Your programs reach the same things. Code calls the API, and a terminal or a coding agent uses the CLI.
- 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
Workflows
Jobs
Events
Runs
Knowledge
APIYour software
Service account
>_
CLIA terminal or a coding agent
Sam Holm
Access follows the account
- Your software calls the API over HTTP, or through SDKs for TypeScript, Python and Go.
- Read lists what your account can see, or fetches a single item, such as one run.
- Change edits a draft, tests it, and publishes the work you checked.
- 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
- A program signs in with an API key, which you create in Settings, under API keys.
- Each key belongs to a person or a service account, and uses that account's current access.
- 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
- Maya sends the contact form on Fjord Living's website, and the shop's server passes it to OAIZ.
- It posts to the publish address, with the API key in the header.
- The body is the event. Its provider is custom, and its properties carry her message.
- OAIZ answers that the event was created, and every live workflow with that trigger starts.
- 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.
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
- The CLI brings the same operations to your terminal.
- To build, get a workflow as a file, edit it, and save it on a new branch.
- Test the branch on the latest real event. By default, a test keeps integration writes off.
- To deploy, merge the branch into main and set it live.
- Apps work the same way. Pull the files, push your changes, and publish.
- 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
.agents/skills/oaiz
- Use the API when your own software works with OAIZ, like a website that sends events.
- Use the CLI when you, a script or a coding agent build, test and deploy workflows and apps.
- 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