[VPC Peerings](https://docs.digitalocean.com/products/networking/vpc/how-to/create-peering/) join two VPC networks with a secure, private connection. This allows resources in those networks to connect to each other's private IP addresses as if they were in the same network.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/digital-ocean-vpc-peerings-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: DigitalOcean VPC Peerings API
version: '2.0'
description: '# Introduction
The DigitalOcean API allows you to manage Droplets and resources within the
DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests.'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
name: DigitalOcean API Team
email: api-engineering@digitalocean.com
termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/
servers:
- url: https://api.digitalocean.com
description: production
security:
- bearer_auth: []
tags:
- name: VPC Peerings
description: 'VPC Peerings
join two VPC networks with a secure, private connection. This allows
resources in those networks to connect to each other''s private IP addresses
as if they were in the same network.'
paths:
/v2/vpc_peerings:
get:
operationId: vpcPeerings_list
summary: List All VPC Peerings
description: To list all of the VPC peerings on your account, send a GET request to `/v2/vpc_peerings`.
tags:
- VPC Peerings
parameters:
- $ref: '#/components/parameters/per_page'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/region'
responses:
'200':
$ref: '#/components/responses/all_vpc_peerings'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/vpc_peerings?region=sfo3&page=1&per_page=20\""
security:
- bearer_auth:
- vpc_peering:read
post:
operationId: vpcPeerings_create
summary: Create a New VPC Peering
description: 'To create a new VPC Peering, send a POST request to `/v2/vpc_peerings`
specifying a name and a list of two VPC IDs to peer. The response code, 202
Accepted, does not indicate the success or failure of the operation, just
that the request has been accepted for processing.'
tags:
- VPC Peerings
requestBody:
required: true
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/vpc_peering_updatable'
- $ref: '#/components/schemas/vpc_peering_create'
required:
- name
- vpc_ids
responses:
'202':
$ref: '#/components/responses/provisioning_vpc_peering'
'401':
$ref: '#/components/responses/unauthorized'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"name\": \"my-first-vpc-peering\", \"vpc_ids\": [ \"997615ce-132d-4bae-9270-9ee21b395e5d\", \"e51aed59-3bb1-4a6a-8de0-9d1329e9c997\"]}' \\\n \"https://api.digitalocean.com/v2/vpc_peerings\""
security:
- bearer_auth:
- vpc_peering:create
/v2/vpc_peerings/{vpc_peering_id}:
get:
operationId: vpcPeerings_get
summary: Retrieve an Existing VPC Peering
description: To show information about an existing VPC Peering, send a GET request to `/v2/vpc_peerings/$VPC_PEERING_ID`.
tags:
- VPC Peerings
parameters:
- $ref: '#/components/parameters/vpc_peering_id'
responses:
'200':
$ref: '#/components/responses/active_vpc_peering'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/vpc_peerings/5a4981aa-9653-4bd1-bef5-d6bff52042e4\""
security:
- bearer_auth:
- vpc_peering:read
patch:
operationId: vpcPeerings_patch
summary: Update a VPC peering
description: To update the name of a VPC peering, send a PATCH request to `/v2/vpc_peerings/$VPC_PEERING_ID` with the new `name` in the request body.
tags:
- VPC Peerings
parameters:
- $ref: '#/components/parameters/vpc_peering_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/vpc_peering_updatable'
required:
- name
responses:
'200':
$ref: '#/components/responses/active_vpc_peering'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X PATCH \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"name\":\"renamed-vpc-peering\"}' \\\n \"https://api.digitalocean.com/v2/vpc_peerings/5a4981aa-9653-4bd1-bef5-d6bff52042e4\""
security:
- bearer_auth:
- vpc_peering:update
delete:
operationId: vpcPeerings_delete
summary: Delete a VPC peering
description: To delete a VPC peering, send a DELETE request to `/v2/vpc_peerings/$VPC_PEERING_ID`.
tags:
- VPC Peerings
parameters:
- $ref: '#/components/parameters/vpc_peering_id'
responses:
'202':
$ref: '#/components/responses/deleting_vpc_peering'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/too_many_requests'
'500':
$ref: '#/components/responses/server_error'
default:
$ref: '#/components/responses/unexpected_error'
x-codeSamples:
- lang: cURL
source: "curl -X DELETE \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/vpc_peerings/6b5c619c-359c-44ca-87e2-47e98170c01d\""
security:
- bearer_auth:
- vpc_peering:delete
components:
schemas:
meta_properties:
type: object
description: Information about the response itself.
properties:
total:
description: Number of objects returned by the request.
type: integer
example: 1
vpc_peering:
type: object
allOf:
- $ref: '#/components/schemas/vpc_peering_base'
- $ref: '#/components/schemas/vpc_peering_create'
- $ref: '#/components/schemas/vpc_peering_updatable'
link_to_last_page:
type: object
properties:
last:
description: URI of the last page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=2
vpc_peering_create:
type: object
properties:
vpc_ids:
type: array
items:
type: string
format: uuid
minItems: 2
maxItems: 2
example:
- c140286f-e6ce-4131-8b7b-df4590ce8d6a
- 994a2735-dc84-11e8-80bc-3cfdfea9fba1
description: An array of the two peered VPCs IDs.
error:
type: object
properties:
id:
description: A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
type: string
example: not_found
message:
description: A message providing additional information about the error, including details to help resolve it when possible.
type: string
example: The resource you were accessing could not be found.
request_id:
description: Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
type: string
example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9
required:
- id
- message
backward_links:
allOf:
- $ref: '#/components/schemas/link_to_first_page'
- $ref: '#/components/schemas/link_to_prev_page'
vpc_peering_base:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4
description: A unique ID that can be used to identify and reference the VPC peering.
created_at:
type: string
format: date-time
readOnly: true
example: '2020-03-13T19:20:47.442049222Z'
description: A time value given in ISO8601 combined date and time format.
status:
type: string
enum:
- PROVISIONING
- ACTIVE
- DELETING
readOnly: true
example: ACTIVE
description: The current status of the VPC peering.
meta:
type: object
properties:
meta:
allOf:
- $ref: '#/components/schemas/meta_properties'
- required:
- total
required:
- meta
link_to_next_page:
type: object
properties:
next:
description: URI of the next page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=2
pagination:
type: object
properties:
links:
$ref: '#/components/schemas/page_links'
link_to_prev_page:
type: object
properties:
prev:
description: URI of the previous page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=1
vpc_peering_updatable:
type: object
properties:
name:
type: string
pattern: ^[a-zA-Z0-9\-]+$
example: nyc1-blr1-peering
description: The name of the VPC peering. Must be unique within the team and may only contain alphanumeric characters and dashes.
region_slug:
type: string
description: The slug identifier for the region where the resource will initially be available.
enum:
- ams1
- ams2
- ams3
- blr1
- fra1
- lon1
- nyc1
- nyc2
- nyc3
- sfo1
- sfo2
- sfo3
- sgp1
- tor1
- syd1
example: nyc3
link_to_first_page:
type: object
properties:
first:
description: URI of the first page of the results.
type: string
example: https://api.digitalocean.com/v2/images?page=1
forward_links:
allOf:
- $ref: '#/components/schemas/link_to_last_page'
- $ref: '#/components/schemas/link_to_next_page'
page_links:
type: object
properties:
pages:
anyOf:
- $ref: '#/components/schemas/forward_links'
- $ref: '#/components/schemas/backward_links'
- {}
example:
pages:
first: https://api.digitalocean.com/v2/account/keys?page=1
prev: https://api.digitalocean.com/v2/account/keys?page=2
responses:
unexpected_error:
description: Unexpected error
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: example_error
message: some error message
provisioning_vpc_peering:
description: The response will be a JSON object with a key called `vpc_peering`. The value of this will be an object that contains the standard attributes associated with a VPC peering.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
type: object
properties:
vpc_peering:
$ref: '#/components/schemas/vpc_peering'
example:
vpc_peering:
id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4
name: example-vpc-peering
vpc_ids:
- 997615ce-132d-4bae-9270-9ee21b395e5d
- e51aed59-3bb1-4a6a-8de0-9d1329e9c997
created_at: '2024-01-09T20:44:32Z'
status: PROVISIONING
all_vpc_peerings:
description: The response will be a JSON object with a key called `vpc_peerings`. This will be set to an array of objects, each of which will contain the standard attributes associated with a VPC peering.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
allOf:
- type: object
properties:
vpc_peerings:
type: array
items:
$ref: '#/components/schemas/vpc_peering'
- $ref: '#/components/schemas/pagination'
- $ref: '#/components/schemas/meta'
example:
vpc_peerings:
- id: 6b5c619c-359c-44ca-87e2-47e98170c01d
name: example-vpc-peering
vpc_ids:
- 997615ce-132d-4bae-9270-9ee21b395e5d
- e51aed59-3bb1-4a6a-8de0-9d1329e9c997
created_at: '2024-01-09T20:44:32Z'
status: ACTIVE
- id: c212b274-911c-44cc-a117-23b7da4a2922
name: another-vpc-peering
vpc_ids:
- 5a100736-b085-4f69-81fd-feee325784bb
- c140286f-e6ce-4131-8b7b-df4590ce8d6a
created_at: '2024-01-10T13:29:58Z'
status: ACTIVE
links: {}
meta:
total: 2
not_found:
description: The resource was not found.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: not_found
message: The resource you requested could not be found.
too_many_requests:
description: API Rate limit exceeded
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: too_many_requests
message: API Rate limit exceeded.
deleting_vpc_peering:
description: The response will be a JSON object with a key called `vpc_peering`. The value of this will be an object that contains the standard attributes associated with a VPC peering.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
type: object
properties:
vpc_peering:
$ref: '#/components/schemas/vpc_peering'
example:
vpc_peering:
id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4
name: example-vpc-peering
vpc_ids:
- 997615ce-132d-4bae-9270-9ee21b395e5d
- e51aed59-3bb1-4a6a-8de0-9d1329e9c997
created_at: '2024-01-09T20:44:32Z'
status: DELETING
active_vpc_peering:
description: The response will be a JSON object with a key called `vpc_peering`. The value of this will be an object that contains the standard attributes associated with a VPC peering.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
type: object
properties:
vpc_peering:
$ref: '#/components/schemas/vpc_peering'
example:
vpc_peering:
id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4
name: example-vpc-peering
vpc_ids:
- 997615ce-132d-4bae-9270-9ee21b395e5d
- e51aed59-3bb1-4a6a-8de0-9d1329e9c997
created_at: '2024-01-09T20:44:32Z'
status: ACTIVE
unauthorized:
description: Unauthorized
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: unauthorized
message: Unable to authenticate you.
server_error:
description: Server error.
headers:
ratelimit-limit:
$ref: '#/components/headers/ratelimit-limit'
ratelimit-remaining:
$ref: '#/components/headers/ratelimit-remaining'
ratelimit-reset:
$ref: '#/components/headers/ratelimit-reset'
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
id: server_error
message: Unexpected server-side error
parameters:
vpc_peering_id:
in: path
name: vpc_peering_id
description: A unique identifier for a VPC peering.
required: true
schema:
type: string
format: uuid
example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4
region:
name: region
in: query
description: The slug identifier for the region where the resource is available.
schema:
$ref: '#/components/schemas/region_slug'
example: nyc3
per_page:
in: query
name: per_page
required: false
description: Number of items returned per page
schema:
type: integer
minimum: 1
default: 20
maximum: 200
example: 2
page:
in: query
name: page
required: false
description: Which 'page' of paginated results to return.
schema:
type: integer
minimum: 1
default: 1
example: 1
headers:
ratelimit-reset:
schema:
type: integer
example: 1444931833
description: The time when the oldest request will expire. The value is given in Unix epoch time. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire.
ratelimit-remaining:
schema:
type: integer
example: 4816
description: The number of requests in your hourly quota that remain before you hit your request limit. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire.
ratelimit-limit:
schema:
type: integer
example: 5000
description: The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.
securitySchemes:
bearer_auth:
type: http
scheme: bearer
description: '## OAuth Authentication
In order to interact with the DigitalOcean API, you or your application must
authenticate.
The DigitalOcean API handles this through OAuth, an open standard for
authorization. OAuth allows you to delegate access to your account.
Scopes can be used to grant full access, read-only access, or access to
a specific set of endpoints.
You can generate an OAuth token by visiting the [Apps & API](https://cloud.digitalocean.com/account/api/tokens)
section of the DigitalOcean control panel for your account.
An OAuth token functions as a complete authentication request. In effect, it
acts as a substitute for a username and password pair.
Because of this, it is absolutely **essential** that you keep your OAuth
tokens secure. In fact, upon generation, the web interface will only display
each token a single time in order to prevent the token from being compromised.
DigitalOcean access tokens begin with an identifiable prefix in order to
distinguish them from other similar tokens.
- `dop_v1_` for personal access tokens generated in the control panel
- `doo_v1_` for tokens generated by applications using [the OAuth flow](https://docs.digitalocean.com/reference/api/oauth-api/)
- `dor_v1_` for OAuth refresh tokens
### Scopes
Scopes act like permissions assigned to an API token. These permissions
determine what actions the token can perform. You can create API
tokens that grant read-only access, full access, or limited access to
specific endpoints by using custom scopes.
Generally, scopes are designed to match HTTP verbs and common CRUD
operations (Create, Read, Update, Delete).
| HTTP Verb | CRUD Operation | Scope |
|---|---|---|
| GET | Read | `<resource>:read` |
| POST | Create | `<resource>:create` |
| PUT/PATCH | Update | `<resource>:update` |
| DELETE | Delete | `<resource>:delete` |
For example, creating a new Droplet by making a `POST` request to the
`/v2/droplets` endpoint requires the `droplet:create` scope while
listing Droplets by making a `GET` request to the `/v2/droplets`
endpoint requires the `droplet:read` scope.
Each endpoint below specifies which scope is required to access it when
using custom scopes.
### How to Authenticate with OAuth
In order to make an authenticated request, include a bearer-type
`Authorization` header containing your OAuth token. All requests must be
made over HTTPS.
### Authenticate with a Bearer Authorization Header
```
curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"
```
'