# Promenaut Website API

The publicly reachable endpoints of the Promenaut website. They accept JSON over HTTPS and return JSON, including structured JSON errors. Full machine-readable description: [/openapi.json](https://www.promenaut.ai/openapi.json).

Promenaut is an enterprise platform delivered through engagements. The platform's agentic workforce is provisioned per customer and is not a self-serve public API. For platform or integration access, use the contact endpoint or email hello@promenaut.ai.

## Base URL

`https://www.promenaut.ai`

## Versioning

- Current version: **v1**.
- Canonical path: `/api/v1/*`. The unversioned `/api/*` alias maps to the same handlers.
- Every response carries an `X-API-Version: 1` header.
- Breaking changes ship under a new version prefix (for example `/api/v2/*`).

## Deprecation policy

- Non-breaking changes are made in place within a version.
- Breaking changes ship under a new version prefix (`/api/v2/*`); the previous version keeps working during the deprecation window.
- A retiring version is announced with a `Deprecation` response header (the deprecation date) and a `Sunset` response header (the removal date, [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) on its responses.
- Minimum notice before removal: **6 months**.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/contact` | Send a contact or demo request. |
| POST | `/api/v1/newsletter` | Subscribe an email address to the newsletter. |
| POST | `/api/v1/request-access` | Request access to a gated resource. |

Example:

```
curl -X POST https://www.promenaut.ai/api/v1/contact \
  -H 'Content-Type: application/json' \
  -d '{"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","company":"Example Bank","intent":"demo"}'
```

## Errors

Errors follow [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) and are served as `application/problem+json`: `type`, `title`, `status`, and `detail`, plus a stable machine-readable `code` and a `hint`. `error`/`message` mirror `title` for backward compatibility.

```json
{
  "type": "https://www.promenaut.ai/api.md#invalid_email",
  "title": "Invalid email format",
  "status": 400,
  "detail": "Provide a valid email address, for example name@company.com.",
  "code": "invalid_email",
  "message": "Invalid email format",
  "hint": "Provide a valid email address, for example name@company.com."
}
```

Unknown `/api/*` paths return a `404` with `code: "not_found"`. Unsupported methods return `405` with `code: "method_not_allowed"`.

## Sandbox / test mode

The endpoints are public and **zero-auth** (no API key needed). To test an integration without creating real records, set `"test": true` (or `"sandbox": true`) in the request body: the input is validated but nothing is submitted, and the response is `{ "success": true, "sandbox": true }`.

```
curl -X POST https://www.promenaut.ai/api/v1/newsletter \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","test":true}'
```

## Rate limits

Responses carry a `RateLimit-Policy` header advertising an advisory limit of 60 requests per 60 seconds so agents can self-throttle. It is advisory and not enforced in-process; `Retry-After` is returned on any `429`.

## See also

- [/openapi.json](https://www.promenaut.ai/openapi.json) — OpenAPI 3.1 description.
- [/developers](https://www.promenaut.ai/developers) — developer overview.
- [/auth.md](https://www.promenaut.ai/auth.md) — how access works.
- [/agents.md](https://www.promenaut.ai/agents.md) — guidance for AI agents.