Ascend REST API
The Ascend REST API lets you programmatically manage runtimes (Workspaces and Deployments), trigger Flow runs, query resources, and interact with Otto. All endpoints are under /api/v1/ on your Instance API.
Base URL
Each Ascend Instance has its own API endpoint:
https://<YOUR_INSTANCE>.api.ascend.io
Replace <YOUR_INSTANCE> with your Instance name. You can find this in the Ascend UI or from your Instance settings.
Authentication
All endpoints except the two under Auth require a Bearer token. To obtain one:
1. Create a service account
In the Ascend UI, go to Settings → Users → Create Service Account. Save the service account ID (asc-sa-...) and Ed25519 private key (base64url-encoded, shown once at creation).
2. Get the JWT audience domain
curl https://<YOUR_INSTANCE>.api.ascend.io/api/v1/auth/config
This returns the cloud_api_domain needed to construct your JWT.
3. Sign a JWT and exchange it for a token
Sign an Ed25519 JWT with the following claims:
| Claim | Value |
|---|---|
iss | Your service account ID (asc-sa-...) |
aud | https://<cloud_api_domain>/auth/token (from step 2) |
iat | Current Unix timestamp |
exp | Expiry (e.g. current time + 300 seconds) |
Then exchange it for an instance access token:
curl -X POST https://<YOUR_INSTANCE>.api.ascend.io/api/v1/auth/token \
-H "Authorization: Bearer <YOUR_SIGNED_JWT>"
The response contains an access_token that you use as a Bearer token for all other API calls.
4. Make authenticated requests
curl https://<YOUR_INSTANCE>.api.ascend.io/api/v1/runtimes \
-H "Authorization: Bearer <ACCESS_TOKEN>"
Endpoint groups
| Group | Description |
|---|---|
| Auth | Token exchange — no pre-existing token required |
| Runtimes | Create, list, update, pause, resume, and delete Workspaces and Deployments |
| Flows | List Flows in a runtime and trigger Flow runs |
| Resources | Query Environments, Projects, and Profiles |
| Otto | Chat with Otto, the AI data engineering assistant, via threads and SSE streaming |