API Reference

This reference covers every REST endpoint exposed by Audra Flow. All endpoints return JSON and follow a consistent response envelope.

Base URL

Authentication

All endpoints (except the authentication endpoints themselves) require a valid JWT bearer token in the Authorization header:

Authorization: Bearer <token>

Tokens are obtained by calling the login endpoint and include the user's roles and permissions. Audra Flow also supports Azure AD SSO for enterprise environments.

Authentication Endpoints

Projects

Projects are the top-level containers in Audra Flow. Each project has its own workspace with isolated artifacts, members, and permissions.

Discovery Artifacts

Discovery is the first phase of the delivery playbook. These endpoints manage goals, stakeholder interviews, and competitor analysis.

Definition Artifacts

Definition artifacts capture user personas, use cases, journeys, service maps, and storyboards.

Each artifact type also supports GET, PATCH, and DELETE on the /:id sub-path for individual record management.

Design & Delivery Artifacts

These endpoints cover user stories, knowledge-base documents, and the delivery workflow.

AI & Product Guru

The AI endpoints power conversations, document processing, and automated project analysis through the Product Guru.

Administration

Users

Roles & Permissions

Templates

Response Format

All successful responses use a consistent envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "pagination": {
      "total": 100,
      "page": 1,
      "pageSize": 20,
      "totalPages": 5
    }
  }
}

The meta.pagination field is included on list endpoints that support pagination.

Error Format

Errors follow the same envelope with an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description of the error",
    "details": { ... }
  }
}

Error Codes

Rate Limiting

API requests are rate-limited to protect service stability:

Rate limit status is communicated via response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Next Steps

• Quick Start — get a local environment running to test API calls.
• System Architecture — see how the API fits into the overall system.
• Developer Guide — learn about branching, testing, and contributing code.