Named Sources API

Server-side aliases for SQL queries.

A named source maps a name to a SQL query stored in CARTO. Your application references the name, so the query text never reaches the browser — useful when the SQL reveals schema details, business logic, or filters you don't want users editing.

You can also restrict a connection to named sources only, which rejects raw SQL entirely. See Named Sources in the user manual.

Endpoint	What it does
POST /v3/named-sources	Create a named source
GET /v3/named-sources	List named sources
GET /v3/named-sources/{name}	Get a named source
PATCH /v3/named-sources/{name}	Update a named source
DELETE /v3/named-sources/{name}	Delete a named source

These endpoints need an OAuth Access Token. See Authorization.

Names are lowercase letters, digits, hyphens and underscores — 3 to 51 characters, starting with a letter or digit and not ending in a hyphen or underscore.

Once created, a named source can be referenced wherever the Maps and SQL APIs accept a query, and granted in an API Access Token like any other source.

Endpoints

Create a named source

post

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/named-sources

Creates a named source — an alias for a SQL query that you can reference from the Maps and SQL APIs without exposing the query itself.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Body

application/json

namestringRequired

Lowercase alphanumerics, hyphens and underscores. Must start with a letter or digit, must not end with a hyphen or underscore, and must be 3 to 51 characters long.

Pattern: ^[a-z0-9][a-z0-9\-_]{2,50}(?<![-_])$

sourcestringRequired

The SQL query this name resolves to.

Responses

200

The named source was created.

application/json

namestringOptional

sourcestringOptional

accountIdstringOptional

userIdstringOptional

createdAtstringOptional

updatedAtstringOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

post/v3/named-sources

HTTPcURLJavaScriptPython

POST /v3/named-sources HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "name": "my_named_source_1",
  "source": "SELECT * FROM carto-demo-data.demo_tables.populated_places LIMIT 100"
}

{
  "name": "text",
  "source": "text",
  "accountId": "text",
  "userId": "text",
  "createdAt": "text",
  "updatedAt": "text"
}

List named sources

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/named-sources

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

searchstringOptional

Filter by name.

pageinteger · min: 1OptionalDefault: 1

pageSizeintegerOptionalDefault: 10

orderBystring · enumOptionalDefault: createdAtPossible values:

orderDirectionstring · enumOptionalDefault: DESCPossible values:

Responses

200

The named sources.

application/json

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

get/v3/named-sources

HTTPcURLJavaScriptPython

GET /v3/named-sources HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "meta": {
    "page": {
      "current": 1,
      "pageSize": 1,
      "total": null,
      "totalPages": null
    }
  },
  "links": {
    "prev": null,
    "next": null
  },
  "data": [
    {
      "name": "text",
      "source": "text",
      "accountId": "text",
      "userId": "text",
      "createdAt": "text",
      "updatedAt": "text"
    }
  ]
}

Get a named source

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/named-sources/{name}

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

namestringRequired

The name of the named source.

Example: my_named_source_1

Responses

200

The named source.

application/json

namestringOptional

sourcestringOptional

accountIdstringOptional

userIdstringOptional

createdAtstringOptional

updatedAtstringOptional

401

The token is missing, malformed or expired.

application/json

404

The named source doesn't exist.

get/v3/named-sources/{name}

HTTPcURLJavaScriptPython

GET /v3/named-sources/{name} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "source": "text",
  "accountId": "text",
  "userId": "text",
  "createdAt": "text",
  "updatedAt": "text"
}

Update a named source

patch

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/named-sources/{name}

Changes the query a named source points to. The name can't change.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

namestringRequired

The name of the named source.

Example: my_named_source_1

Body

application/json

sourcestringRequired

Responses

200

The updated named source.

application/json

namestringOptional

sourcestringOptional

accountIdstringOptional

userIdstringOptional

createdAtstringOptional

updatedAtstringOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

404

The resource doesn't exist.

application/json

patch/v3/named-sources/{name}

HTTPcURLJavaScriptPython

PATCH /v3/named-sources/{name} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "source": "SELECT geom, pop_max FROM carto-demo-data.demo_tables.populated_places LIMIT 500"
}

{
  "name": "text",
  "source": "text",
  "accountId": "text",
  "userId": "text",
  "createdAt": "text",
  "updatedAt": "text"
}

Delete a named source

delete

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/named-sources/{name}

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

namestringRequired

The name of the named source.

Example: my_named_source_1

Responses

204

The named source was deleted.

No content

401

The token is missing, malformed or expired.

application/json

404

The resource doesn't exist.

application/json

delete/v3/named-sources/{name}

HTTPcURLJavaScriptPython

DELETE /v3/named-sources/{name} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content