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

# API reference

> Discover and configure workspace Connections and Capabilities with the Marina API.

The Marina API lets workspace administrators automate the same Connection
setup available in the dashboard. Activating a supported Connection publishes
its standard Capability automatically; applications do not configure that
Capability separately.

## Authentication

Create an API key under **Settings → API keys**. Use a key with `read`
permission for discovery and add `write` permission to configure Connections.
The user who created the key must remain a workspace administrator.

Send the key as a bearer token:

```bash theme={null}
export MARINA_TOKEN="mar_…"
export MARINA_API="$(curl --fail-with-body https://marina.cloud/.well-known/marina | jq -r .api_url)"

curl --fail-with-body "${MARINA_API}/v1/connectors" \
  -H "Authorization: Bearer ${MARINA_TOKEN}"
```

API keys remain active until revoked. Keep them out of source control and
rotate them from **Settings → API keys**.

## Discover the API

`GET /v1/` returns the current resource paths and methods for connector setup.

```bash theme={null}
curl --fail-with-body "${MARINA_API}/v1/" \
  -H "Authorization: Bearer ${MARINA_TOKEN}"
```

`GET /v1/connectors` returns the available connector catalog. Each connector
includes:

* supported authentication modes;
* JSON Schemas for public configuration and write-only credentials;
* operations and their read or edit effect;
* standard Capabilities supplied when the Connection becomes active.

Use these schemas instead of hard-coding connector fields or defaults.

## Configure a BigQuery Connection

### 1. Create the Connection

```bash theme={null}
curl --fail-with-body "${MARINA_API}/v1/integrations" \
  -X POST \
  -H "Authorization: Bearer ${MARINA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics warehouse",
    "connector": "bigquery",
    "auth_mode": "organization",
    "config": {
      "project_id": "customer-data",
      "location": "US",
      "maximum_bytes_billed": 100000000000
    }
  }'
```

Save the returned `integration.id` for the following requests.

### 2. Add the credential

Use a dedicated service account with only the datasets Marina should read.
The credential is write-only: API responses report whether a Connection is
configured but never return credential values.

If the service-account JSON is stored in `service-account.json`, send only the
fields required by the connector schema:

```bash theme={null}
jq '{credential: {
  client_email,
  private_key,
  private_key_id
}}' service-account.json | curl --fail-with-body \
  "${MARINA_API}/v1/integrations/${INTEGRATION_ID}/connection" \
  -X PUT \
  -H "Authorization: Bearer ${MARINA_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

### 3. Verify and activate

```bash theme={null}
curl --fail-with-body \
  "${MARINA_API}/v1/integrations/${INTEGRATION_ID}/connection/verify" \
  -X POST \
  -H "Authorization: Bearer ${MARINA_TOKEN}"

curl --fail-with-body \
  "${MARINA_API}/v1/integrations/${INTEGRATION_ID}/activate" \
  -X POST \
  -H "Authorization: Bearer ${MARINA_TOKEN}"
```

Activation automatically supplies `analytics.bigquery.query`. Confirm the
published Capability with:

```bash theme={null}
curl --fail-with-body "${MARINA_API}/v1/capabilities" \
  -H "Authorization: Bearer ${MARINA_TOKEN}"
```

## Connection endpoints

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/v1/connectors` | Discover connector contracts. |
| `GET` | `/v1/integrations` | List configured Connections. |
| `POST` | `/v1/integrations` | Create a Connection. |
| `GET` | `/v1/integrations/{integration}` | Read one Connection. |
| `PATCH` | `/v1/integrations/{integration}` | Update its name or configuration. |
| `PUT` | `/v1/integrations/{integration}/connection` | Add or replace its credential. |
| `DELETE` | `/v1/integrations/{integration}/connection` | Remove its credential. |
| `POST` | `/v1/integrations/{integration}/connection/verify` | Test the configured Connection. |
| `POST` | `/v1/integrations/{integration}/activate` | Activate it and supply Capabilities. |
| `POST` | `/v1/integrations/{integration}/disable` | Disable it. |
| `GET` | `/v1/capabilities` | List published Capabilities. |

An `{integration}` value may be a Connection ID or its unique name.

## Errors

Errors use a stable JSON envelope:

```json theme={null}
{
  "error": {
    "code": "invalid_input",
    "message": "invalid connector configuration at project_id"
  }
}
```

Treat the HTTP status as the request outcome and `error.code` as the
machine-readable category. Credential values are not included in error
responses.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.