- Your own programs can work with OAIZ through its API. Here is one request, from the key to the answer.
Developer
Call the API
Your code reads OAIZ and sends it events, signed with an API key.
$ curl https://api.oaiz.io/ingest/workflows \
-H "Authorization: Bearer $OAIZ_API_KEY"
{ "items": [
{ "name": "Customer requests" },
{ "name": "Weekly report" }
], "hasMore": false, "nextCursor": null }
- A program proves who it is with an API key. You create one in Settings, under API keys.
- Name the key and choose when it expires. Pick a service account when a system, not a person, owns it.
- The key reaches only what its owner can reach.
- The full key shows only once. Copy it into your program's secret settings.
Create an API key
Name it, set an expiry, choose an owner
It uses its owner's access
Copy it once
API keysCreate
NameOwnerExpires
reporting-scriptSam HolmHumanNever
Create API key
Create API Key
Choose a name and expiration date.
API Key Name
shop-backend
Expiration Date
31 Dec 2027
No expiration date
Service Account (Optional)
No service account (personal key)
Shop backend
Generate API key
Generated API Key
Copy and store it in a safe place.
oaiz_sk_ex*****_***_*_****_***
CopyCopied
This API key is shown only once. Copy it before leaving this page.
Settings → API keys
Create and manage the keys for your organisation.
Who owns the key
No service account makes a personal key. A service account is for a system.
Owner's access
The key has no separate permission list. Change the owner's access to change what it reaches.
Shown once
Store it in your program's secret settings. The list never shows it again.
- Keep the key on your server, in an environment variable, and out of browser code.
- Every request carries it in the Authorization header, after the word Bearer.
Keep it on your server
Send it with every request
$ export OAIZ_API_KEY=oaiz_sk_example_not_a_real_key
Your serverAn environment variable
Browser codeNever put the key here
Request header
Authorization: Bearer $OAIZ_API_KEY
- Start with a read. This request lists the workflows the key can see.
- The answer is JSON. The workflows sit in a list called items.
- When hasMore is true, send nextCursor back to fetch the next page.
- A 401 means the key was not accepted. A 403 means its owner is not allowed to do this.
Start with a read
The answer is JSON
Follow the cursor
When a request is refused
$ curl "https://api.oaiz.io/ingest/workflows?pageSize=2" \
-H "Authorization: Bearer $OAIZ_API_KEY"
{
"items": [
{ "name": "Customer requests", "status": "Live", "jobCount": 5 },
{ "name": "Weekly report", "status": "Live", "jobCount": 2 }
],
"hasMore": true,
"nextCursor": "3f9c2a10-7d4e-4b8a-9c61-2e5f0a7b4d13"
}
List workflows
GET /ingest/workflows
items
One entry per workflow, with its id, name, status, jobCount and more. The sample shows a few fields.
Next page
Same filters, plus the cursor:
?pageSize=2&cursor=3f9c2a10-…
401Authentication failed
The key was missing or not accepted.
403Not allowed
The key's owner may not do this operation.
- Next, something useful. Your system can send OAIZ an event, such as a customer message.
- Post it to the publish address, with the provider custom for your own systems.
- Properties hold the content. A unique key stops OAIZ from storing the same event twice.
- OAIZ answers Event published, with the event's ID.
- Every live workflow whose trigger is that event type starts.
Send an event
Post to the publish address
Content, and a unique key
Event published
Live workflows start
$ 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": "Please change my billing address to 12 Example Street."
},
"uniqueKey": "ticket-1042"
}'
{"message":"Event published","uuid":"8d2e61b4-5a0c-4f3e-9b7d-1c4a2f6e0b95"}
Publish an event
POST /ingest/event/publish
provider: custom
uniqueKey
One event per type and key in your organisation. A repeat is not stored again.
201Event published
The uuid is the event's ID.
e:custom/customer-message
message: "Please change my billing address to 12 Example Street."
Live workflow
Trigger: customer-message
- In code, the SDKs for TypeScript, Python and Go make the same calls and follow every page for you.
- You can now create a key, read your workflows and send an event. The API page in the docs links to every endpoint.
The same calls from code
Your first requests
TypeScript
listWorkflowsPagesiterateListWorkflows
Python
list_workflows_pagesiter_list_workflows
Go
ListWorkflowsPagesIterateListWorkflows