# Introduction

# Becoming You Labs Partner API

The partner API lets you run Becoming You Labs assessments on behalf of your own
users. You create a session, submit answers, complete it, and read back the
scored results, all keyed to an identifier you control.

## Base URL

```
https://api.becomingyou.com
```

## Products

Every route is product-scoped as `/v1/{product}/...`. One product is available
today:

| Product       | Path segment    |
| ------------- | --------------- |
| Values Bridge | `values-bridge` |

## Endpoints

| Method | Path                                          | Purpose                                        |
| ------ | --------------------------------------------- | ---------------------------------------------- |
| `GET`  | `/v1/{product}/assessment`                    | Fetch the assessment definition and its items. |
| `POST` | `/v1/{product}/sessions`                      | Start a session for one of your subjects.      |
| `GET`  | `/v1/{product}/sessions/{id}`                 | Read a session's current state.                |
| `POST` | `/v1/{product}/sessions/{id}/answers`         | Submit answers to a session.                   |
| `POST` | `/v1/{product}/sessions/{id}/complete`        | Close a session and trigger scoring.           |
| `GET`  | `/v1/{product}/sessions/{id}/results`         | Read the scored results for a session.         |
| `GET`  | `/v1/{product}/subjects/{externalId}/results` | Read results by your own subject identifier.   |

See the [API Reference](/api) for request and response schemas.

## Errors

Requests rejected at the gateway (a missing or invalid API key, an exceeded rate
limit) return an RFC 9457 problem document:

```json
{
  "type": "https://httpproblems.com/http-status/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No Authorization Header",
  "instance": "/v1/values-bridge/sessions"
}
```

Requests that reach the API return a stable error envelope instead. Branch on
`error.code`, never on `error.message`:

```json
{
  "error": {
    "code": "not_found",
    "message": "Session not found."
  }
}
```

| Code                  | Status |
| --------------------- | ------ |
| `unauthorized`        | 401    |
| `forbidden`           | 403    |
| `not_found`           | 404    |
| `unsupported_product` | 404    |
| `conflict`            | 409    |
| `invalid_request`     | 422    |
| `internal_error`      | 500    |

`internal_error` responses are always redacted to a generic message.