Skip to main content
This guide walks you through authenticating with the Ekso API and making your first requests. For details on API architecture, error formats, and response conventions, see the API overview.

​
Base URL

All API requests target your tenant’s subdomain: 
https://{tenant}.ekso.app/api/
Replace {tenant} with your organization’s subdomain.

​
Authentication

Ekso uses OAuth 2.0 with PKCE. The flow works like this:
1

Discover endpoints

Fetch the OAuth metadata from your tenant:
curl https://{tenant}.ekso.app/.well-known/oauth-authorization-server
This returns the authorization, token, and registration endpoints.
2

Authorize and get a token

Direct the user to the authorization endpoint with a PKCE code challenge. After the user approves, exchange the authorization code for an access token at the token endpoint.See the full OAuth 2.0 details in the API reference.
3

Include the token in requests

Add the token to every API request:
curl https://{tenant}.ekso.app/api/board \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
List your boards

Once authenticated, list the boards visible to your account: 
curl https://{tenant}.ekso.app/api/board \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
[
  {
    "entity": "b1a2c3d4-...",
    "name": "Q1 Sprint Board",
    "description": "Main delivery board for Q1",
    "budgetHours": 400,
    "locked": false,
    "archived": false
  }
]

​
Create an item

Items are the core unit of work in Ekso. Each item belongs to a container and follows a process that defines its workflow. To create an item, you need a containerId and a processId. List your containers first: 
curl https://{tenant}.ekso.app/api/container \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Then create the item: 
curl -X POST https://{tenant}.ekso.app/api/item \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "CONTAINER_ID",
    "processId": "PROCESS_ID",
    "field": [
      { "fieldId": "Name", "value": "Fix login timeout" }
    ]
  }'
The response includes the item’s key (e.g., GEM-123), status, and all field values.
Items carry a dynamic set of fields controlled by their process and container permissions. To understand the full field model, discover available field types, and use the screen endpoint for permission-aware field discovery, see Items and fields.

​
Error handling

If something goes wrong, the API returns a JSON error with a kind, message, and optional fields array: 
{
  "kind": "Validation",
  "message": "Human-readable error description",
  "fields": [
    { "field": "containerId", "code": "required" }
  ]
}
Common status codes: 400 (validation), 403 (permission), 422 (business logic), 500 (server error). See the API overview for the full error reference.

​
Next steps

API overview

Authentication details, error format, and response conventions.

API reference

Full REST API with all endpoints and schemas.

MCP tools

Connect AI agents directly to Ekso — no REST calls needed.