Posit Tags API
The Tags API from Posit — 5 operation(s) for tags.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
email: support@posit.co
name: Posit Connect Support
url: https://support.posit.co/hc/en-us
description: "## Overview\n\nThe Posit Connect Server API can be used to perform certain\nuser actions remotely. You will need to install a tool or library\nthat can make HTTP requests. We recommend using one of our SDKs, which\nare designed to make it easier to interact with the API.\n\n- Python: [posit-sdk](https://github.com/posit-dev/posit-sdk-py/)\n- R: [connectapi](https://posit-dev.github.io/connectapi/)\n\nThe SDKs are designed to work with the following values set in environment\nvariables, though you may provide them directly to the SDK if you prefer:\n\n- `CONNECT_SERVER` - The URL of the Posit Connect server.\n- `CONNECT_API_KEY` - Your API key.\n\nPlease note that all API paths are relative to the base API URL\n(e.g., `https://connect.example.com/__api__`).\nUnless otherwise noted, all endpoints which accept a request body\nwill require the body to be in JSON format.\nSimilarly, all response bodies will be returned in JSON format.\n\n### Specifications {#download}\n\nThe Posit Connect Server API OpenAPI specification is available for\ndownload as either JSON or YAML. Both formats contain the same\ninformation, also presented on this page.\n\n* <a href=\"openapi.json\" title=\"OpenAPI (JSON)\" target=\"_blank\">OpenAPI (JSON)</a>\n* <a href=\"openapi.yaml\" title=\"OpenAPI (YAML)\" target=\"_blank\">OpenAPI (YAML)</a>\n\n### Versioning of the API {#versioning-policy}\n\nThe Posit Connect Server API uses a simple, single number versioning scheme as noted\nas the first part of each endpoint path. This version number will only be incremented\nin the event that non-backward compatible changes are made to an existing endpoint.\nNote that this occurs on a per-endpoint basis; see the section on\n[deprecation](#deprecation) below for more information.\n\nChanges that are considered backward compatible are:\n\n* New fields in responses.\n* New non-required fields in requests.\n* New endpoint behavior which does not violate the current functional intent of the\n endpoint.\n\nChanges that are considered non-backward compatible are:\n\n* Removal or rename of request or response fields.\n* A change of the type or format of one or more request or response fields.\n* Addition of new required request fields.\n* A substantial deviation from the current functional intent of the endpoint.\n\nThe points relating to functional intent are assumed to be extremely rare as more\noften such situations will result in a completely new endpoint, which makes the\nchange a backward compatible addition.\n\n#### Experimentation\n\nPosit Connect labels experimental endpoints in the API by including `/experimental`\nin the endpoint path immediately after the version indicator. If an endpoint is noted\nas experimental, it should not be relied upon for any production work. These are\nendpoints that Posit Connect is making available to our customers to solicit\nfeedback; they are subject to change without notice. Such changes include anything\nfrom altered request/response shapes, to complete abandonment of the endpoint.\n\nThis public review of an experimental endpoint will last as long as necessary to either\nprove its viability or to determine that it's not really needed. The time for this\nwill vary based on the intricacies of each endpoint. When the endpoint is finalized,\nthe next release of Posit Connect will mark the experimental path as deprecated while\nadding the endpoint without the `/experimental` prefix. The path with the experimental\nprefix will be removed six months later. The documentation for the endpoint will also\nnote, during that time, the original, experimental, path.\n\nAll experimental endpoints are clearly marked as such in this documentation.\n\n#### Deprecation and removal of old versions {#deprecation}\n\nIt is possible that Posit Connect may decide to deprecate an endpoint. This will\nhappen if either the endpoint serves no useful purpose because its functionality is\nnow handled by a different endpoint or because there is a newer version of the endpoint\nthat should be used.\n\nIf a deprecated endpoint is called, the response to it will include an extra HTTP\nheader called, `X-Deprecated-Endpoint` and will have as a value the path of the\nendpoint that should be used instead. If the functionality has no direct replacement,\nthe value will be set to `n/a`.\n\nDeprecated versions of an endpoint will be supported for 1 year from the release date\nof Posit Connect in which the endpoint was marked as deprecated. At that time, the\nendpoint is subject to removal at the discretion of Posit Connect. The life cycle\nof an endpoint will follow these steps.\n\n1. The `/v1/endpoint` is public and in use by Posit Connect customers.\n1. Posit Connect makes `/v2/experimental/endpoint` available for testing and feedback.\n Customers should still use `/v1/endpoint` for production work.\n1. Posit Connect moves version 2 of the endpoint out of experimentation so, all within\n the same release:\n 1. `/v1/endpoint` is marked as deprecated.\n 1. `/v2/experimental/endpoint` is marked as deprecated.\n 1. `/v2/endpoint` is made public.\n1. Six months later, `/v2/experimental/endpoint` is removed from the product.\n1. Twelve months later, `/v1/endpoint` is removed from the product.\n\nNote that it is possible that Posit Connect may produce a new version of an existing\nendpoint without making an experimental version of it first. The same life cycle,\nwithout those parts, will still be followed.\n\n### Authentication {#authentication}\n\nAPI endpoints require you to identify yourself as a valid Posit Connect\nuser. You do this by specifying an API key when you make a call to the\nserver. The [API Keys](../user/api-keys/) chapter of the Posit Connect\nUser Guide explains how to create an API key.\n\n#### API Keys {#api-keys}\n\nAPI keys are managed by each user in the Posit Connect\ndashboard. If you ever lose an API key or otherwise feel it has\nbeen compromised, use the dashboard to revoke the key and create\nanother one.\n\n**WARNING**: Keep your API key safe. If your Posit Connect server's URL does not begin\nwith `https`, your API key could be intercepted and used by a malicious actor.\n\nOnce you have an API key, you can authenticate by passing the key with a prefix\nof `\"Key \"` (the space is important) in the Authorization header.\n\nBelow are examples of invoking the \"Get R Information\" endpoint.\n\n##### cURL\n\n```bash\ncurl -H \"Authorization: Key XXXXXXXXXXX\" \\\n https://positconnect.example.com/__api__/v1/server_settings/r\n```\n\n##### R\n\n```r\nlibrary(httr)\napiKey <- \"XXXXXXXXXXX\"\nresult <- GET(\"https://positconnect.example.com/__api__/v1/server_settings/r\",\n add_headers(Authorization = paste(\"Key\", apiKey)))\n```\n\n##### Python\n\n```python\nimport requests\nr = requests.get(\n 'https://positconnect.example.com/__api__/v1/server_settings/r',\n headers = { 'Authorization': 'Key XXXXXXXXXXX' }\n)\n```\n\n### API CORS considerations {#api-cors-considerations}\n\nFor information about using Connect's API from web applications in different domains,\nsee the [Cross-Origin Resource Sharing (CORS)](../admin/security/index.md#cors) section in\nthe security documentation.\n\n### Request correlation {#request-correlation}\n\nPosit Connect assigns a correlation ID to every API request via the\n`X-Correlation-ID` HTTP header. Connect includes this identifier in the response\nheaders and in server-side log entries, making it possible to trace a specific\nrequest through the system.\n\nIf you include an `X-Correlation-ID` header in your request, Connect preserves that\nvalue. If you do not include the header, Connect generates a Universally Unique\nIdentifier (UUID) automatically. Either way, the same value is returned in the\nresponse header.\n\nThis header is useful for:\n\n- **Debugging failed requests**: provide the correlation ID to your administrator so\n they can locate the corresponding server-side log entries.\n- **Correlating client-side and server-side activity**: set a known correlation ID in\n your client and match it against server logs or OpenTelemetry traces.\n\n**Example**\n\n```bash\n# Let Connect generate a correlation ID\ncurl -H \"Authorization: Key XXXXXXXXXXX\" -i \\\n https://positconnect.example.com/__api__/v1/user\n# Response includes: X-Correlation-ID: <generated-uuid>\n\n# Provide your own correlation ID\ncurl -H \"Authorization: Key XXXXXXXXXXX\" \\\n -H \"X-Correlation-ID: my-request-123\" -i \\\n https://positconnect.example.com/__api__/v1/user\n# Response includes: X-Correlation-ID: my-request-123\n```\n\n### API error codes {#api-error-codes}\n\n{{< include src/api_codes.fragment.html >}}\n"
license:
name: Commercial. Copyright 2015-2026 Posit Software, PBC. All Rights Reserved.
url: https://posit.co/about/eula/
termsOfService: https://posit.co/about/eula/
title: Posit Connect API Reference API Keys Tags API
version: 1.0.1
servers:
- url: /__api__
security:
- apiKey: []
tags:
- name: Tags
paths:
/v1/content/{guid}/tags:
get:
description: 'List of all tags for the specified content item.
Authenticated access required from an admin or from a user with at least viewer
permissions on the content item.'
operationId: listContentTags
parameters:
- in: path
name: guid
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Tag'
type: array
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: List tags for content
tags:
- Tags
post:
description: 'Add the specified tag to an individual content item. When adding a tag,
all tags above the specified tag in the tag tree are also added to the
content item.
Authenticated access required from an admin or from a user with
collaborator/editor permissions on the content item.'
operationId: addTag
parameters:
- in: path
name: guid
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentTagInput'
required: true
responses:
'200':
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: Add tag to content
tags:
- Tags
/v1/content/{guid}/tags/{id}:
delete:
description: 'Remove the specified tag from an individual content item. When removing
a tag, all children and descendant tags are also removed from the content
item.
Authenticated access required from an admin or from a user with
collaborator/editor permissions on the content item.'
operationId: removeTag
parameters:
- in: path
name: guid
required: true
schema:
format: uuid
type: string
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: Remove tag from content
tags:
- Tags
/v1/tags:
get:
description: 'List of all tags.
Authenticated access from a user is required.'
operationId: listTags
parameters:
- in: query
name: name
schema:
type: string
- in: query
name: parent_id
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Tag'
type: array
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: List tags
tags:
- Tags
post:
description: 'Create a new tag. Tags without a parent are considered tag "categories"
and are used to organize other tags. Note that tag categories cannot be
added to content items.
Authenticated access from a user having an "administrator" role is required.'
operationId: createTag
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TagInput'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: Create tag
tags:
- Tags
/v1/tags/{id}:
delete:
description: 'Deletes a tag, including all descendants in its own tag hierarchy.
Authenticated access from a user having an "administrator" role is required.'
operationId: deleteTag
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: Delete tag
tags:
- Tags
get:
description: 'Get an individual tag by its identifier or by a comma-delimited "path"
to the tag. The path to the tag is the series of tag names to traverse
the tag hierarchy, starting with a tag category.
Authenticated access from a user is required.'
operationId: getTag
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: Get tag
tags:
- Tags
patch:
description: 'Update an existing tag.
Authenticated access from a user having an "administrator" role is required.'
operationId: updateTag
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TagInput'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: Update tag
tags:
- Tags
/v1/tags/{id}/content:
get:
description: 'List all of the content for the specified tag.
Authenticated access from a user is required. If an "administrator"
role is used, then all content items will be returned regardless of
the visibility to the requesting user.'
operationId: listTagContent
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Content'
type: array
description: Successful response.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested operation requires authentication.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: You do not have permission to perform this operation.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: The requested object does not exist.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
description: A server error occurred.
summary: List content for tags
tags:
- Tags
components:
schemas:
ScheduleVariant:
additionalProperties: false
description: Variant information embedded in a schedule.
properties:
key:
description: The variant key.
example: default
type: string
name:
description: The variant name.
example: Default Variant
type: string
is_default:
description: Whether this is the default variant.
example: true
type: boolean
type: object
Schedule:
description: Base schedule information for a content item.
properties:
type:
description: The schedule type.
example: rrule
type: string
schedule:
allOf:
- $ref: '#/components/schemas/RRuleSet'
description: The recurrence rule in RFC5545 format.
next_run:
description: The next scheduled run time. Null if no future runs are scheduled.
format: date-time
nullable: true
type: string
email:
description: Whether email notifications are enabled for this schedule.
example: false
type: boolean
timezone:
description: The timezone for this schedule.
example: America/New_York
type: string
start_time:
description: The start time of the schedule window.
format: date-time
nullable: true
type: string
end_time:
description: The end time of the schedule window. Null if the schedule runs indefinitely.
format: date-time
nullable: true
type: string
last_run:
allOf:
- $ref: '#/components/schemas/ScheduleLastRun'
description: Information about the last scheduled run.
nullable: true
type: object
ContentOwner:
additionalProperties: false
description: Basic details about the owner of a content item.
properties:
guid:
description: The owner's unique identifier.
example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce
format: uuid
type: string
username:
description: The owner's username.
example: jondoe
nullable: true
type: string
first_name:
description: The owner's first name.
example: Jon
nullable: true
type: string
last_name:
description: The owner's last name.
example: Doe
nullable: true
type: string
type: object
Content:
additionalProperties: false
description: The content object models all the "things" you may deploy to Posit Connect. This includes Shiny applications, R Markdown documents, Jupyter notebooks, Plumber APIs, FastAPI and Flask APIs, Python apps, plots, and pins.
properties:
guid:
description: The unique identifier of this content item.
example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce
format: uuid
type: string
name:
description: 'A simple identifier. Allows alpha-numeric
characters, periods (`"."`), hyphens (`"-"`), and underscores (`"_"`).'
example: quarterly-analysis
type: string
title:
description: The title of this content.
example: Quarterly Analysis of Team Velocity
nullable: true
type: string
description:
description: A rich description of this content.
example: This report calculates per-team statistics ...
type: string
access_type:
description: 'Access type describes how this content manages its viewers. The
value `all` is the most permissive; any visitor to Posit Connect
will be able to view this content. The value `logged_in` indicates
that all Posit Connect accounts may view the content. The `acl`
value lets specifically enumerated users and groups view the
content. Users configured as collaborators may always view content.
Access types may be restricted by the Connect configuration or the
product license.'
example: acl
type: string
locked:
description: Whether or not the content is locked.
example: false
type: boolean
locked_message:
description: 'A custom message that is displayed by the content item when locked.
It is possible to format this message using Markdown.'
example: '# This piece of content is locked'
type: string
connection_timeout:
description: 'Maximum number of seconds allowed without data sent or received
across a client connection. A value of `0` means connections will
never time-out (not recommended). When `null`, the default
[`Scheduler.ConnectionTimeout`](../admin/appendix/configuration/index.md#Scheduler.ConnectionTimeout) is used. Applies only to content types
that are executed on demand.'
example: 3600
format: int32
nullable: true
type: integer
read_timeout:
description: 'Maximum number of seconds allowed without data received from a
client connection. A value of `0` means a lack of client (browser)
interaction never causes the connection to close. When `null`, the
default [`Scheduler.ReadTimeout`](../admin/appendix/configuration/index.md#Scheduler.ReadTimeout) is used. Applies only to content
types that are executed on demand.'
example: 3600
format: int32
nullable: true
type: integer
init_timeout:
description: 'The maximum number of seconds allowed for an interactive application
to start. Posit Connect must be able to connect to a newly
launched application before this threshold has
elapsed. When `null`, the default [`Scheduler.InitTimeout`](../admin/appendix/configuration/index.md#Scheduler.InitTimeout) is used.
Applies only to content types that are executed on demand.'
example: 60
format: int32
nullable: true
type: integer
idle_timeout:
description: 'The maximum number of seconds a worker process for an interactive
application to remain alive after it goes idle (no active
connections). When `null`, the default [`Scheduler.IdleTimeout`](../admin/appendix/configuration/index.md#Scheduler.IdleTimeout) is
used. Applies only to content types that are executed on demand.'
example: 5
format: int32
nullable: true
type: integer
max_processes:
description: 'Specifies the total number of concurrent processes allowed for a
single interactive application per Posit Connect node. When `null`,
the default [`Scheduler.MaxProcesses`](../admin/appendix/configuration/index.md#Scheduler.MaxProcesses) is used. Applies only to
content types that are executed on demand.'
example: 3
format: int32
nullable: true
type: integer
min_processes:
description: 'Specifies the minimum number of concurrent processes allowed for a
single interactive application per Posit Connect node. When `null`,
the default `Scheduler.MinProcesses` is used. Applies only to
content types that are executed on demand.'
example: 0
format: int32
nullable: true
type: integer
max_conns_per_process:
description: 'Specifies the maximum number of client connections allowed to an
individual process. Incoming connections which will exceed this
limit are routed to a new process or rejected. When `null`, the
default [`Scheduler.MaxConnsPerProcess`](../admin/appendi
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/posit/refs/heads/main/openapi/posit-tags-api-openapi.yml