> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Programmatically manage test suites, flows, and app builds via the Autosana API

The Autosana API allows you to programmatically create test suites, flows, and upload app builds. This is useful for integrating Autosana with your own automation platforms, AI agents, or CI/CD pipelines.

<Tip>
  For a simpler CI/CD setup using GitHub Actions, see [CI/CD Integration](/ci-cd-integration). The endpoints below are for custom integrations.
</Tip>

## Base URL

```
https://backend.autosana.ai
```

All API endpoints are relative to this base URL.

***

## Authentication

All API requests require an API key passed in the `X-API-Key` header.

```bash theme={null}
curl -X POST https://backend.autosana.ai/api/v1/suites \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Test Suite"}'
```

<ParamField header="X-API-Key" type="string" required>
  Your organization's API key. Get it from the welcome quickstart or [Settings → Integrations](https://autosana.ai/settings?tab=integrations).
</ParamField>

***

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Suites & Flows" icon="list-check" href="/api-suites-flows">
    Create and list test suites and flows
  </Card>

  <Card title="Runs" icon="play" href="/api-runs">
    Trigger flows, poll for results, and fetch run details
  </Card>

  <Card title="Hooks" icon="bolt" href="/api-hooks">
    Manage setup, teardown, and runtime hook scripts
  </Card>

  <Card title="Environment Variables" icon="key" href="/api-env-vars">
    List environments and manage their env vars (including secrets)
  </Card>

  <Card title="CI/CD Upload" icon="upload" href="/api-ci">
    Upload app builds programmatically
  </Card>
</CardGroup>

***

## Error Responses

| Status Code | Description                                            |
| ----------- | ------------------------------------------------------ |
| **400**     | Bad request - missing or invalid parameters            |
| **401**     | Missing API key                                        |
| **403**     | Invalid API key                                        |
| **404**     | Resource not found                                     |
| **422**     | Validation error - check the response body for details |
| **500**     | Server error                                           |

#### Example Error Response

```json theme={null}
{
  "detail": "Suite not found"
}
```

***

## Rate Limits

The API is rate-limited to prevent abuse. If you receive a `429 Too Many Requests` response, wait a few seconds before retrying.

***

## Use Cases

<CardGroup cols={2}>
  <Card title="AI Test Generation" icon="robot">
    Generate test cases from requirements using AI, then push them to Autosana via the API
  </Card>

  <Card title="JIRA Integration" icon="ticket">
    Automatically create test suites when tickets move to "Ready for QA" status
  </Card>

  <Card title="Test Sync" icon="arrows-rotate">
    Keep Autosana tests in sync with your test management system
  </Card>

  <Card title="Bulk Import" icon="upload">
    Migrate existing test cases from spreadsheets or other tools
  </Card>
</CardGroup>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Writing Effective Tests" icon="pen" href="/flows#writing-effective-flow-instructions">
    Learn how to write clear, reliable test instructions
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:founders@autosana.ai">
    Reach out if you need help with your integration
  </Card>
</CardGroup>