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

# API introduction

> Authentication, base URL, roles, and conventions for the VendexLabs API.

The VendexLabs API is a REST API over HTTPS. Everything in the product — vendors, lists, assessments, and portfolio metrics — is available programmatically so you can automate onboarding, sync assessments with your systems, and build custom reporting.

## Base URL

The API is served from your deployment's API gateway. Throughout these docs we use:

```
https://api.vendexlabs.com
```

Replace it with the base URL configured for your environment. All paths below are relative to this base.

## Authentication

Requests are authenticated with a **bearer token** issued by Amazon Cognito. Send it in the `Authorization` header:

```bash theme={null}
curl https://api.vendexlabs.com/vendors/all \
  -H "Authorization: Bearer <ID_OR_ACCESS_TOKEN>"
```

The token identifies the calling user by email; the API resolves that user's organization membership and role to authorize each request.

<Warning>
  Treat tokens like passwords. Never embed them in client-side code or commit them to source control.
</Warning>

## Organization scope

Most endpoints operate on a single organization, identified by an `account-id` query parameter (your organization's UUID):

```
GET /vendor-lists?account-id=<ORG_UUID>
```

Use the literal value `individual` to work with personal (non-organization) data scoped to the authenticated user.

## Roles & permissions

Access is governed by the caller's role in the organization. Each role includes the ones below it.

| Role       | API access                                                               |
| ---------- | ------------------------------------------------------------------------ |
| **Viewer** | Read (`GET`) list, metrics, assessment, and subscriber data.             |
| **Member** | Viewer access plus writes to vendors, lists, assessments, and documents. |
| **Admin**  | Member access plus membership management.                                |
| **Owner**  | Full control, including assigning the owner role.                        |

<Note>
  A separate **platform admin** group gates global vendor operations (bulk enrichment and manual vendor edits). This is distinct from your organization role — see the [Vendors](/api/vendors) endpoints marked *admin only*.
</Note>

## Conventions

* **Format** — Request and response bodies are JSON. Send `Content-Type: application/json` on writes.
* **IDs** — Resources are identified by UUIDs. Vendors can also be addressed by canonical name.
* **Timeouts** — The API gateway enforces a **30-second** integration timeout. Long operations (like large CSV imports) are chunked — send them in batches and follow the `has_more` / `next_row_offset` cursors in the response.
* **Errors** — Standard HTTP status codes: `400` invalid request, `401` missing/invalid token, `403` insufficient role, `404` not found, `409` conflict. Error responses include a message describing the problem.

## Next

<CardGroup cols={2}>
  <Card title="Vendors" icon="building" href="/api/vendors">
    Read the vendor directory and vendor profiles.
  </Card>

  <Card title="Vendor lists" icon="list-check" href="/api/vendor-lists">
    Manage the vendors your organization tracks.
  </Card>

  <Card title="Assessments" icon="clipboard-check" href="/api/assessments">
    Create and update assessments and evidence.
  </Card>

  <Card title="Metrics" icon="chart-line" href="/api/metrics">
    Portfolio posture, incidents, and history.
  </Card>
</CardGroup>