# Overview

Welcome to the Opine API! This is your gateway to programmatically access and manage data from your Opine organization. The API is designed to be intuitive, consistent, and secure—providing powerful capabilities for developers building custom integrations, internal tools, and data pipelines.

### Base URL

All requests are made to the following base URL:

```
https://api.tryopine.com
```

### Authentication

All API requests must be authenticated using an API key. You can provide the API key using the `X-API-Key` header in your requests:

```http
X-API-Key: YOUR_API_KEY
```

API keys can be generated and managed by **organization administrators** at the following URL:

👉 <https://app.tryopine.com/settings/api-keys>

Each key can be scoped to specific APIs to control access. Scopes define the operations permitted by the key:

* Use `*` scope for full read/write access.
* Use `*:read` scope for full read access
* You can define more granular scopes when generating the key.

### Data Format

All endpoints use and return **JSON**. Make sure to include the appropriate `Content-Type` header for requests that include a body:

```http
Content-Type: application/json
```

### Pagination

APIs that return collections of resources use **offset-based pagination**. You can control the number of results and their position using these query parameters:

| Parameter | Type   | Description                            |
| --------- | ------ | -------------------------------------- |
| `limit`   | Number | Maximum number of items to return      |
| `skip`    | Number | Number of items to skip from the start |

Example:

```
GET /v1/users?limit=25&skip=50
```

### Error Handling

When validation errors occur (e.g. due to incorrect data or missing fields), the API returns a structured JSON response with details about what went wrong.

#### Example validation error:

```json
{
  "error": "Validation error.",
  "issues": [
    {
      "received": "INVALID",
      "code": "invalid_enum_value",
      "options": ["PENDING", "ACCEPTED", "REJECTED", "REVOKED"],
      "path": ["status"],
      "message": "Invalid enum value. Expected 'PENDING' | 'ACCEPTED' | 'REJECTED' | 'REVOKED', received 'PENDIN'"
    }
  ]
}
```

Each issue in the `issues` array includes:

* `path`: the location of the error in the payload
* `code`: the type of validation failure
* `message`: a human-readable message
* Additional details like `received` and `options`, depending on the error type