# VeroniQA for developers

VeroniQA's public API is a free, keyless sandbox: ask questions about the demo API and get cited
answers, read the measured results, and fetch the demo API's OpenAPI spec. Models are simulated,
so answers are extracts from the documents. Nothing you send is stored.

- Base URL: `https://veroniqa.vercel.app/api`
- OpenAPI 3.1: [https://veroniqa.vercel.app/openapi.json](https://veroniqa.vercel.app/openapi.json) (also [YAML](https://veroniqa.vercel.app/api/openapi.yaml))
- API catalog (RFC 9727): [https://veroniqa.vercel.app/.well-known/api-catalog](https://veroniqa.vercel.app/.well-known/api-catalog)
- Official CLI: `veroniqa` (Python, no dependencies)

## Quickstart

1. Check the service: `curl https://veroniqa.vercel.app/api/v1/status`
2. Ask a question:

```bash
curl -X POST https://veroniqa.vercel.app/api/v1/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "What is the p95 latency target for the order list?"}'
```

3. Or use the CLI:

```bash
pipx install "git+https://github.com/Zapkid/agentqa#subdirectory=clients/veroniqa-cli"
veroniqa status
veroniqa ask "What is the p95 latency target for the order list?"
veroniqa results --json
```

Run it once without installing: `uvx --from "git+https://github.com/Zapkid/agentqa#subdirectory=clients/veroniqa-cli" veroniqa status`

## Authentication and API keys

None. The public API is a sandbox for the demo, so there are no accounts or keys; each client is
rate limited instead. To test your own API with real models, run VeroniQA yourself from
[the repository](https://github.com/Zapkid/agentqa).

## Endpoints

| method | path | what it does |
|---|---|---|
| `GET` | `/api/` | API index |
| `GET` | `/api/v1/status` | Service status |
| `GET` | `/api/v1/results` | Measured results |
| `POST` | `/api/v1/ask` | Ask about the demo API |
| `GET` | `/api/v1/demo/openapi.json` | OpenAPI spec of the demo API |

Request and response schemas are in the [OpenAPI description](https://veroniqa.vercel.app/openapi.json).

## Errors

Every error under `/api` is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem
document, served as `application/problem+json`, with a stable `code` and a `hint`:

```json
{
  "type": "https://veroniqa.vercel.app/developers#error-invalid_request",
  "title": "Invalid request",
  "status": 422,
  "detail": "The request body is not valid.",
  "instance": "/api/v1/ask",
  "code": "invalid_request",
  "hint": "Fix the fields listed in `errors`; the request schema is in /openapi.json.",
  "errors": [
    {
      "field": "question",
      "message": "Field required"
    }
  ]
}
```

| code | status | title | how to fix |
|---|---|---|---|
| `not_found` | 404 | Not found | Check the path against the OpenAPI description at /openapi.json. |
| `method_not_allowed` | 405 | Method not allowed | Use the method listed for this path in /openapi.json (see the Allow header). |
| `invalid_request` | 422 | Invalid request | Fix the fields listed in `errors`; the request schema is in /openapi.json. |
| `rate_limited` | 429 | Too many requests | Wait for the number of seconds in Retry-After, then retry. |
| `internal_error` | 500 | Internal error | Retry later; if it persists, open an issue at https://github.com/Zapkid/agentqa/issues. |

## Rate limits

- `default`: 60 requests per 60 seconds per client
- `ask`: 10 requests per 60 seconds per client

Every response carries `RateLimit-Policy` and `RateLimit` headers
([draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/)),
for example `RateLimit: "default";r=59;t=60`. A `429 rate_limited` response adds `Retry-After`.

## Sandbox

- The interactive app: [https://veroniqa.vercel.app/talk/](https://veroniqa.vercel.app/talk/) (no sign-up; a private, temporary workspace)
- The demo API that VeroniQA tests: [its OpenAPI spec](https://veroniqa.vercel.app/api/v1/demo/openapi.json)

## Versioning

The API is versioned in the path (`/v1`); the current release is 1.0.0.
Breaking changes get a new version path.

## Machine-readable files

- [openapi.json](https://veroniqa.vercel.app/openapi.json), [openapi.yaml](https://veroniqa.vercel.app/openapi.yaml)
- [api-catalog](https://veroniqa.vercel.app/.well-known/api-catalog)
- [llms.txt](https://veroniqa.vercel.app/llms.txt)
- [sitemap.xml](https://veroniqa.vercel.app/sitemap.xml)