# uidex API

The uidex CLI includes an API client for querying and managing uidex resources (organizations, projects, reports, integrations, etc.).

## Authentication

```bash
npx uidex api login                      # Interactive browser login (opens browser, creates a personal access token)
npx uidex api login --token <tok>        # Store a token directly
npx uidex api status                     # Check auth state
```

Tokens are stored at `~/.uidex/cloud-token.json`. The `UIDEX_TOKEN` env var overrides the stored token.

## Making requests

```bash
npx uidex api <METHOD> <PATH> [flags]
```

### Flags

| Flag               | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `--body <json>`    | Request body (JSON string)                               |
| `--query <params>` | Query string (`key=val&key2=val2`)                       |
| `--base-url <url>` | Override API base URL (default: `https://app.uidex.dev`) |
| `--token <tok>`    | Use a specific token for this request                    |
| `--raw`            | Disable JSON pretty-printing                             |
| `--no-color`       | Disable colored output                                   |

Use `UIDEX_API_URL` env var to permanently override the base URL (e.g. for local dev at `http://localhost:4339`).

## Discovering routes

```bash
npx uidex api --list                     # List all routes
npx uidex api --list --tag Reports       # Filter by tag
npx uidex api --list --json              # JSON output
```

## Common workflows

### List organizations and projects

```bash
npx uidex api GET /api/organizations
npx uidex api GET /api/organizations/{orgId}/projects
```

### Query reports

```bash
# All reports in an org
npx uidex api GET /api/organizations/{orgId}/reports

# Reports for a specific project
npx uidex api GET /api/organizations/{orgId}/projects/{projectId}/reports

# Filter with query params (status, type, severity, search, page, limit)
npx uidex api GET /api/organizations/{orgId}/projects/{projectId}/reports \
  --query "status=open&type=bug&limit=10"

# Single report detail
npx uidex api GET /api/organizations/{orgId}/projects/{projectId}/feedback/{reportId}
```

### Update a report

```bash
npx uidex api PATCH /api/organizations/{orgId}/projects/{projectId}/feedback/{reportId} \
  --body '{"status":"resolved"}'
```

### Resolve a project key

Given a project key (e.g. from `NEXT_PUBLIC_UIDEX_PROJECT_KEY` in `.env.local`), resolve it to the project and org in one call:

```bash
npx uidex api GET /api/projects/resolve --query "key=ux_dev_6ghJQlUj-OfgvKvbyQCGc8ugqgYe_xjO"
```

Returns `{ organization, project, apiKey }` with full details.

### Manage integrations

```bash
npx uidex api GET /api/organizations/{orgId}/integrations
npx uidex api POST /api/organizations/{orgId}/integrations/{integrationId}/test
```

### Issue drafts

```bash
npx uidex api GET /api/organizations/{orgId}/issue-drafts
npx uidex api POST /api/organizations/{orgId}/issue-drafts/{draftId}/submit
```

## Route tags

Routes are grouped by tag: `Ingest`, `Organizations`, `Members`, `Invitations`, `Projects`, `API Keys`, `Reports`, `Integrations`, `External Issues`, `Issue Drafts`, `Triage`, `User Tokens`, `CLI Auth`. Use `--list --tag <Tag>` to explore a specific group.

## Resolving IDs

Most routes require `orgId` and `projectId` path parameters. To resolve them:

- **From a project key** (fastest): `GET /api/projects/resolve?key=<raw_key>` → returns both `organization.id` and `project.id`
- **From scratch**: `GET /api/organizations` → find org by `slug`, then `GET /api/organizations/{orgId}/projects` → find project by `slug`

When working in a repo that has uidex configured, read `NEXT_PUBLIC_UIDEX_PROJECT_KEY` from `.env.local` (or `.env`) and use the resolve endpoint to get the org and project IDs in one call.