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

# API Reference

> REST API reference for Control Plane covering Core and Audit APIs, Bearer token authentication, service account keys, and user access tokens.

## Overview

Two APIs are available:

* **Core API** - Main API for managing Control Plane resources
* **Audit API** - API for querying and creating audit events

## API Endpoints

| API   | Endpoint URL                                               | Fallback Swagger API Documentation                                             |
| :---- | :--------------------------------------------------------- | :----------------------------------------------------------------------------- |
| Core  | [https://api.cpln.io/](https://api.cpln.io/)               | [https://console.cpln.io/openapi/core](https://console.cpln.io/openapi/core)   |
| Audit | [https://audit.cpln.io/audit](https://audit.cpln.io/audit) | [https://console.cpln.io/openapi/audit](https://console.cpln.io/openapi/audit) |

## Authentication

The Control Plane APIs use Bearer token authentication. All API requests must include an authorization header with a valid token.

### Obtaining Authorization Tokens

You can authenticate using one of the following methods:

#### Service Account Key

[Create a service account](/guides/create-service-account) in your organization with the necessary permissions, then generate a service account key. This key can be used as an API token.

#### User Access Token

If you're using the [Control Plane CLI](/cli-reference/overview), first log in by running [cpln login](/cli-reference/commands/login). This opens a browser where you can authenticate using your identity provider (Google, Microsoft, etc.). After logging in, your CLI profile receives an access token that is used for all subsequent requests.

To obtain this access token, run:

```bash theme={null}
cpln profile token <profile-name>
```

Replace `<profile-name>` with the name of your logged-in [CLI profile](/cli-reference/commands/profile#profile-get). Use the returned token as your authorization token.

### Using Authentication

Include your token in the `Authorization` header of all API requests:

```bash theme={null}
Authorization: Bearer YOUR_TOKEN_HERE
```

Example with cURL:

```bash theme={null}
curl --request GET \
  --url https://api.cpln.io/org/{org}/gvc/{name} \
  --header 'Authorization: YOUR_TOKEN_HERE'
```

## Using the Interactive API Playground

Each endpoint in this documentation includes a **"Try it"** button that opens an interactive API playground. You can use this to:

1. **Test endpoints directly** - Make live API calls without leaving the documentation
2. **See request/response examples** - View formatted JSON responses
3. **Copy code samples** - Get ready-to-use cURL, Python, or JavaScript examples

### Example: Getting a GVC

To get a GVC (Global Virtual Cloud) using the interactive playground:

1. Navigate to the **GVC** section in the Core API
2. Click on **"Get a GVC by name"**
3. Click the green **"Try it"** button
4. Enter your authorization token in the authentication field
5. Fill in the required parameters:
   * `org`: Your organization name (e.g., `my-org`)
   * `name`: The name of your GVC (e.g., `my-gvc`)
6. Click **"Send"** to execute the request

The response will display the GVC details in JSON format, which you can copy or use as a reference for your own API calls.

### Example Request

Here's a complete example of getting a GVC using cURL:

```bash theme={null}
curl --request GET \
  --url https://api.cpln.io/org/my-org/gvc/my-gvc \
  --header 'Authorization: YOUR_TOKEN_HERE'
```

Successful response:

```json theme={null}
{
  "kind": "gvc",
  "id": "aac813e3-0fef-423f-9dcd-630f5a59e56a",
  "name": "my-gvc",
  "alias": "a1gm4cx40er00",
  "description": "my-gvc",
  "version": 12,
  "tags": {},
  "created": "2024-01-10T21:50:46.156Z",
  "lastModified": "2025-11-20T13:09:31.150Z",
  "spec": {
    "env": [
      {
        "name": "KEY",
        "value": "VALUE"
      }
    ],
    "loadBalancer": {
      "trustedProxies": 0
    },
    "staticPlacement": {
      "locationLinks": ["/org/my-org/location/aws-eu-central-1"]
    }
  },
  "links": [
    {
      "rel": "self",
      "href": "/org/my-org/gvc/my-gvc"
    },
    {
      "rel": "org",
      "href": "/org/my-org"
    },
    {
      "rel": "workload",
      "href": "/org/my-org/gvc/my-gvc/workload"
    },
    {
      "rel": "identity",
      "href": "/org/my-org/gvc/my-gvc/identity"
    }
  ],
  "status": {}
}
```