API reference

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:

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.

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

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:

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

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:

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:

{
  "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.

Get started

Guides

Platform services

Connections

Reference

Authentication

Discover the API

Configure a BigQuery Connection

1. Create the Connection

2. Add the credential

3. Verify and activate

Connection endpoints

Errors

​Authentication

​Discover the API

​Configure a BigQuery Connection

​1. Create the Connection

​2. Add the credential

​3. Verify and activate

​Connection endpoints

​Errors

Authentication

Discover the API

Configure a BigQuery Connection

1. Create the Connection

2. Add the credential

3. Verify and activate

Connection endpoints

Errors