Skip to content
AiQu Docs

REST API

Everything the web interface does, it does over a REST API that you can use directly. The interactive specification is served by your own installation at /api/ with the raw OpenAPI document at /api/swagger.json - that is the authoritative endpoint list, and it matches the version you are actually running.

This page covers the part the specification does not explain well: how authentication works.

Authentication is two calls

Section titled “Authentication is two calls”

A session is created first, then exchanged for a token. Both are then sent on every subsequent request, as two separate headers.

  1. Create a session. GET /api/auth returns a session id and a nonce.

    Terminal window
    curl -s https://app.example.aiqu.ai/api/auth
    {"result":[{"nonce":1300398300,"session":"ca909fdb-…"}],"status":"success"}

  2. Exchange it for a token. POST /api/auth with the session, the nonce, and your credentials.

    Terminal window
    curl -s -X POST https://app.example.aiqu.ai/api/auth \
      -H 'Content-Type: application/json' \
      -d '{"session":"ca909fdb-…","nonce":1300398300,
           "username":"you@example.com","password":"…"}'
    {"result":[{"token":"7f6207a6…","userid":10,"validto":"…"}],"status":"success"}

  3. Call the API with both values, as separate headers.

    Terminal window
    curl -s https://app.example.aiqu.ai/api/user/permission \
      -H "Session: ca909fdb-…" \
      -H "Token: 7f6207a6…"

Responses

Section titled “Responses”

Every response is wrapped the same way:

{ "status": "success", "result": [ … ] }

status is success or error. On an error, result carries the message. result is usually a list even when it holds one object, so result[0] is the normal way in.

Signing out

Section titled “Signing out”

DELETE /api/auth with the Session header ends the session. Tokens also expire on their own - validto in the login response says when.

Checking what you are

Section titled “Checking what you are”

Useful when a script behaves differently from the person who wrote it:

Terminal window
curl -s .../api/user/permission -H "Session: …" -H "Token: …"
# {"result":[{"realmadmin":false}],"status":"success"}

Permissions apply identically

Section titled “Permissions apply identically”

The API enforces exactly what the interface does. A group without the add-job permission gets a refusal from POST /api/job just as it gets a disabled button in the form. Nothing is reachable over the API that the same account could not reach in the browser.

Endpoint groups

Section titled “Endpoint groups”
Prefix Covers Needs
/auth Sessions, registration, password reset, invitations —
/job Submitting, listing, editing, cancelling User
/storage Buckets and their contents User
/queue Queues, and the queue-to-node mapping User
/user Your own profile and permissions User
/admin/… Users, groups, queues, storage, nodes, projects Tenant admin
/superadmin/… Tenants, global nodes and queues, impersonation Superadmin

Consult /api/swagger.json on your own installation for the exact shapes - this table is a map, not a contract.