Posit Connect API Reference

Overview

The Posit Connect Server API can be used to perform certain user actions remotely. You will need to install a tool or library that can make HTTP requests. We recommend using one of our SDKs, which are designed to make it easier to interact with the API.

• Python: posit-sdk
• R: connectapi

The SDKs are designed to work with the following values set in environment variables, though you may provide them directly to the SDK if you prefer:

• CONNECT_SERVER - The URL of the Posit Connect server.
• CONNECT_API_KEY - Your API key.

Please note that all API paths are relative to the base API URL (e.g., https://connect.example.com/__api__). Unless otherwise noted, all endpoints which accept a request body will require the body to be in JSON format. Similarly, all response bodies will be returned in JSON format.

Specifications

The Posit Connect Server API OpenAPI specification is available for download as either JSON or YAML. Both formats contain the same information, also presented on this page.

• OpenAPI (JSON)
• OpenAPI (YAML)

Versioning of the API

The Posit Connect Server API uses a simple, single number versioning scheme as noted as the first part of each endpoint path. This version number will only be incremented in the event that non-backward compatible changes are made to an existing endpoint. Note that this occurs on a per-endpoint basis; see the section on deprecation below for more information.

Changes that are considered backward compatible are:

• New fields in responses.
• New non-required fields in requests.
• New endpoint behavior which does not violate the current functional intent of the endpoint.

Changes that are considered non-backward compatible are:

• Removal or rename of request or response fields.
• A change of the type or format of one or more request or response fields.
• Addition of new required request fields.
• A substantial deviation from the current functional intent of the endpoint.

The points relating to functional intent are assumed to be extremely rare as more often such situations will result in a completely new endpoint, which makes the change a backward compatible addition.

Experimentation

Posit Connect labels experimental endpoints in the API by including /experimental in the endpoint path immediately after the version indicator. If an endpoint is noted as experimental, it should not be relied upon for any production work. These are endpoints that Posit Connect is making available to our customers to solicit feedback; they are subject to change without notice. Such changes include anything from altered request/response shapes, to complete abandonment of the endpoint.

This public review of an experimental endpoint will last as long as necessary to either prove its viability or to determine that it’s not really needed. The time for this will vary based on the intricacies of each endpoint. When the endpoint is finalized, the next release of Posit Connect will mark the experimental path as deprecated while adding the endpoint without the /experimental prefix. The path with the experimental prefix will be removed six months later. The documentation for the endpoint will also note, during that time, the original, experimental, path.

All experimental endpoints are clearly marked as such in this documentation.

Deprecation and removal of old versions

It is possible that Posit Connect may decide to deprecate an endpoint. This will happen if either the endpoint serves no useful purpose because its functionality is now handled by a different endpoint or because there is a newer version of the endpoint that should be used.

If a deprecated endpoint is called, the response to it will include an extra HTTP header called, X-Deprecated-Endpoint and will have as a value the path of the endpoint that should be used instead. If the functionality has no direct replacement, the value will be set to n/a.

Deprecated versions of an endpoint will be supported for 1 year from the release date of Posit Connect in which the endpoint was marked as deprecated. At that time, the endpoint is subject to removal at the discretion of Posit Connect. The life cycle of an endpoint will follow these steps.

1. The /v1/endpoint is public and in use by Posit Connect customers.
2. Posit Connect makes /v2/experimental/endpoint available for testing and feedback. Customers should still use /v1/endpoint for production work.
3. Posit Connect moves version 2 of the endpoint out of experimentation so, all within the same release:
   1. /v1/endpoint is marked as deprecated.
   2. /v2/experimental/endpoint is marked as deprecated.
   3. /v2/endpoint is made public.
4. Six months later, /v2/experimental/endpoint is removed from the product.
5. Twelve months later, /v1/endpoint is removed from the product.

Note that it is possible that Posit Connect may produce a new version of an existing endpoint without making an experimental version of it first. The same life cycle, without those parts, will still be followed.

Authentication

API endpoints require you to identify yourself as a valid Posit Connect user. You do this by specifying an API key when you make a call to the server. The API Keys chapter of the Posit Connect User Guide explains how to create an API key.

API Keys

API keys are managed by each user in the Posit Connect dashboard. If you ever lose an API key or otherwise feel it has been compromised, use the dashboard to revoke the key and create another one.

WARNING: Keep your API key safe. If your Posit Connect server’s URL does not begin with https, your API key could be intercepted and used by a malicious actor.

Once you have an API key, you can authenticate by passing the key with a prefix of "Key " (the space is important) in the Authorization header.

Below are examples of invoking the “Get R Information” endpoint.

cURL

curl -H "Authorization: Key XXXXXXXXXXX" \
     https://positconnect.example.com/__api__/v1/server_settings/r

R

library(httr)
apiKey <- "XXXXXXXXXXX"
result <- GET("https://positconnect.example.com/__api__/v1/server_settings/r",
  add_headers(Authorization = paste("Key", apiKey)))

Python

import requests
r = requests.get(
  'https://positconnect.example.com/__api__/v1/server_settings/r',
  headers = { 'Authorization': 'Key XXXXXXXXXXX' }
)

API CORS considerations

For information about using Connect’s API from web applications in different domains, see the Cross-Origin Resource Sharing (CORS) section in the security documentation.

API error codes

Error Code	Message	HTTP status	HTTP message
1	An internal failure occurred.	500	Internal Server Error
2	The requested method or endpoint is not supported.	404	Not Found
3	The requested object ID is invalid.	400	Bad Request
4	The requested object does not exist.	404	Not Found
5	Application name must be between 3 and 64 alphanumeric characters, periods, hyphens, and underscores.	400	Bad Request
6	The password is not strong enough. Please try again.	400	Bad Request
7	The requested username is not permitted.	400	Bad Request
8	The requested username is already in use. Usernames are case sensitive. Please ensure you are using the correct case.	409	Conflict
9	The requested user could not be found.	404	Not Found
10	The requested object doesn’t belong to you.	403	Forbidden
11	The requested filter could not be applied.	400	Bad Request
12	A required parameter is missing.	400	Bad Request
13	The requested range is invalid.	400	Bad Request
14	Group name must be between less than 4096 alphanumeric characters.	400	Bad Request
15	The requested group name is already in use.	409	Conflict
16	The user is already a member of the group.	409	Conflict
17	The requested item could not be removed because it does not exist.	404	Not Found
18	The requested item could not be changed because it does not exist.	404	Not Found
19	You don’t have permission to access this item.	403	Forbidden
20	You don’t have permission to remove this item.	403	Forbidden
21	You don’t have permission to change this item.	403	Forbidden
22	You don’t have permission to perform this operation.	403	Forbidden
23	You don’t have permission to give the user this role.	403	Forbidden
24	The requested operation requires authentication.	401	Unauthorized
25	The parameter is invalid.	400	Bad Request
26	An object with that name already exists.	409	Conflict
27	This version of R is in use and cannot be deleted.	409	Conflict
28	No application bundle to deploy.	404	Not Found
29	The token is expired. Authentication tokens must be claimed within one hour.	401	Unauthorized
30	We couldn’t log you in with the provided credentials. Please ask your administrator for assistance.	401	Unauthorized
31	Password change prohibited.	403	Forbidden
32	The requested filter is not valid.	400	Bad Request
33	This user cannot be added as a collaborator because they don’t have permission to publish content.	403	Forbidden
34	The application’s owner cannot be added as a collaborator or viewer.	400	Bad Request
35	Cannot delete object as it is being used elsewhere.	409	Conflict
36	This user’s username has already been set and cannot be changed.	400	Bad Request
37	Invalid start time: start time is required and must be after 01/01/2010 and before end time.	400	Bad Request
38	The manifest.json is invalid or missing.	400	Bad Request
39	The application does not support this action.	400	Bad Request
40	The current user has not been confirmed.	400	Bad Request
41	The initial user must specify a password; it cannot be generated.	400	Bad Request
42	The user has already been confirmed.	400	Bad Request
43	This system has not been configured to send email (missing sender). Please contact your administrator.	400	Bad Request
44	The current user does not have an email address.	400	Bad Request
45	Invalid MinProcesses setting. The MinProcesses setting may not exceed the Scheduler.MinProcessesLimit setting.	400	Bad Request
46	Internal user fields cannot be changed via API.	400	Bad Request
47	You cannot log in because the configured policy requires that the Posit Connect administrator provision your account first. Please contact your administrator.	403	Forbidden
48	You cannot change the type of application once deployed. Try deploying this as a new application instead of updating an existing one.	403	Forbidden
49	You don’t have permission to lock/unlock this user.	403	Forbidden
50	This user is locked.	403	Forbidden
51	Vanity path conflicts with one or more already in use.	409	Conflict
52	Vanity path is not permitted.	400	Bad Request
53	Immutable field cannot be changed.	400	Bad Request
54	You cannot set this content to run as the current user	400	Bad Request
55	Custom RunAs settings are only allowed for executable content.	400	Bad Request
56	The RunAs setting references a prohibited Unix account.	400	Bad Request
57	The RunAs setting does not reference a valid Unix account.	400	Bad Request
58	The RunAs setting references a Unix account that does not have the correct group membership.	400	Bad Request
59	There is no rendering available.	400	Bad Request
60	This email address is not allowed to login to this server.	400	Bad Request
61	You cannot change the role of the only remaining administrator.	400	Bad Request
62	An API key name cannot be blank or have more than 80 characters.	400	Bad Request
63	There was a problem communicating with the LDAP authentication server. Please contact your administrator.	400	Bad Request
64	The number of users permitted by this license has been exceeded. Please contact your administrator.	400	Bad Request
65	API applications are not permitted by your license.	403	Forbidden
66	You cannot assign ownership to another user.	400	Bad Request
67	You must provide the source_key for an existing variant	400	Bad Request
68	You cannot promote a variant without a valid rendering	400	Bad Request
69	The bundle ID of the source and target variants must match	400	Bad Request
70	Target rendering is more recent than source rendering	400	Bad Request
71	Only parameterized documents support promoting output	400	Bad Request
72	Not allowed to create schedule with different application association than its variant	400	Bad Request
73	You may not schedule ad-hoc variants	400	Bad Request
74	The requested report name is not permitted	400	Bad Request
75	You may not delete the active bundle for an application or a bundle that is referenced by a variant	400	Bad Request
76	A user using the same Unique ID already exists	400	Bad Request
77	A tag name cannot be more than 255 characters	400	Bad Request
78	A tag must have a name	400	Bad Request
79	Cannot assign a category to an app	400	Bad Request
80	The target object does not match the provided version.	409	Conflict
81	Duplicate names are not permitted; a sibling tag or category already has this name	400	Bad Request
82	The bundle for deployment must belong to the target application.	400	Bad Request
83	Too many search results. Be more specific.	400	Bad Request
84	The token has already been claimed. Tokens can only be claimed once.	403	Forbidden
85	A token using the same token key already exists	400	Bad Request
86	A new token MUST contain a public_key and token in the json body.	400	Bad Request
87	The request body cannot be parsed	400	Bad Request
88	Cannot apply the requested change because it would make the target object an ancestor of itself.	400	Bad Request
89	Unable to send email. Please contact your administrator.	400	Bad Request
90	User self-registration is disabled.	400	Bad Request
91	The external authentication provider did not provide a valid username.	400	Bad Request
92	XSRF token mismatch	403	Forbidden
93	Private variants cannot be configured to email users other than the owner	403	Forbidden
94	You can only request a permissions upgrade once per 24-hour period.	400	Bad Request
95	This API does not allow the current authentication type.	403	Forbidden
96	Incorrect current password.	403	Forbidden
97	Changing host or scheme in redirect is forbidden.	403	Forbidden
98	We couldn’t log you in with the provided credentials. Please ask your administrator for assistance.	401	Unauthorized
99	Please re-supply your credentials.	401	Unauthorized
100	Unable to remove item. It is being processed.	400	Bad Request
101	The provided password change token is invalid.	403	Forbidden
102	A schedule for this variant already exists.	409	Conflict
103	This system has not been configured to send email (missing server address). Please contact your administrator.	400	Bad Request
104	The content checksum header and body MD5 sum are not equal.	400	Bad Request
105	TensorFlow Model APIs are not permitted by your license.	403	Forbidden
106	Unable to update environment variables because they were changed while you were editing them.	409	Conflict
107	That username is not allowed because it is prohibited by policy.	400	Bad Request
108	Environment changes contain a prohibited variable	409	Conflict
109	This type of content is not allowed because it is prohibited by policy.	403	Forbidden
110	You cannot change the categorization of content once deployed. Try deploying this as a new application instead of updating an existing one.	403	Forbidden
111	You cannot change if an app is parameterized once deployed. Try deploying this as a new application instead of updating an existing one.	403	Forbidden
112	The provided user role is not recognized.	400	Bad Request
113	Invalid MaxProcesses setting. The MaxProcesses setting may not exceed the Scheduler.MaxProcessesLimit setting.	400	Bad Request
114	Invalid MinProcesses setting. The MinProcesses setting may not exceed the MaxProcesses setting.	400	Bad Request
115	The provided status is not recognized.	400	Bad Request
116	The requested rendering does not match the variant.	400	Bad Request
117	Unknown access type.	400	Bad Request
118	This access type is not allowed because it is prohibited by policy.	403	Forbidden
119	The authentication provider does not support creating records from a retrieved ticket. POST new content instead.	400	Bad Request
120	The authentication provider does not support creating records from POST content. PUT a retrieved ticket instead.	400	Bad Request
121	The request JSON is invalid.	400	Bad Request
122	Application title must be between 3 and 1024 characters.	400	Bad Request
123	Application description must be 4096 characters or less.	400	Bad Request
124	No administrator has a configured email address.	400	Bad Request
125	Content-Length cannot be 0.	400	Bad Request
126	Request Content-Length did not match the number of bytes received.	400	Bad Request
127	The temp_ticket is invalid.	400	Bad Request
128	The email address cannot be blank.	400	Bad Request
129	The user unique ID cannot be blank.	400	Bad Request
130	The group unique ID cannot be blank.	400	Bad Request
131	A group using the same unique ID already exists.	400	Bad Request
132	The configured provider cannot access this endpoint.	400	Bad Request
133	The source variant belongs to a different app.	400	Bad Request
134	Unable to write bundle to disk.	400	Bad Request
135	Unable to extract the bundle.	400	Bad Request
136	Time values must be in RFC3339 format.	400	Bad Request
137	The start of the time interval cannot be in the past, or more than 5 years in the future.	400	Bad Request
138	The end of the time interval cannot be earlier than the start time.	400	Bad Request
139	The length of the time interval cannot be more than 1 year.	400	Bad Request
140	The time interval must have both start and end times.	400	Bad Request
141	Task lookup failures can indicate that a load balancer is not using sticky sessions or a client is not including the session cookie. Details: https://docs.posit.co/connect/admin/load-balancing/	404	Not Found
142	The app is already managed by git.	409	Conflict
143	The app is not managed by git.	409	Conflict
144	Uploading a content bundle is not allowed for this application since it is managed by git.	409	Conflict
145	Git support is disabled.	400	Bad Request
146	Git URLs must be absolute and cannot have username, query, or fragment.	400	Bad Request
147	The specified app mode is not executable.	400	Bad Request
148	The specified app mode is not valid.	400	Bad Request
149	Environment changes contain a duplicated variable name.	409	Conflict
150	The load factor must be between 0.0 and 1.0.	400	Bad Request
151	The timeout must be between 0 and 2592000 seconds.	400	Bad Request
152	The principal type must be ‘user’ or ‘group’.	400	Bad Request
153	The requested group could not be found.	404	Not Found
154	The requested user is already in the content permission list.	409	Conflict
155	The requested group is already in the content permission list.	409	Conflict
156	This user cannot be assigned as the owner because they don’t have permission to publish content.	403	Forbidden
157	The requested parent tag does not exist	400	Bad Request
158	The requested tag does not exist	400	Bad Request
159	The permission request submitted already exists.	409	Conflict
160	The email notification for a permission request cannot be delivered due to missing or invalid email address.	400	Bad Request
161	The include option specified is not valid	400	Bad Request
162	The specified hostname is not an active Connect host	400	Bad Request
163	The specified job cannot be terminated because it is not active	409	Conflict
164	Git URLs must use HTTP or HTTPS.	400	Bad Request
165	Cannot create bootstrapping user due to existing users	403	Forbidden
166	The provided JWT is invalid	401	Unauthorized
167	The controls file coundn’t be read.	500	Internal Server Error
168	The title must be between 1 and 64 characters.	400	Bad Request
169	The description cannot be more than 4096 characters.	400	Bad Request
170	The cluster_name must be ‘Kubernetes’.	400	Bad Request
171	A unique name for the environment must be provided.	400	Bad Request
172	Unknown matching type.	400	Bad Request
173	The installation path must be an absolute Unix filepath.	400	Bad Request
174	The installation version must use semantic version format.	400	Bad Request
175	An environment with that name already exists.	409	Conflict
176	The specified service account name is not a valid DNS subdomain.	400	Bad Request
177	The supervisor path may not contain any of the following whitespace control characters:	400	Bad Request
178	The specified service account is not registered for use when running content.	400	Bad Request
179	Unsupported runtime language identifier	400	Bad Request
180	The request did not identify a cache location	400	Bad Request
181	Invalid MemoryRequest setting. The MemoryRequest setting cannot be less than 0 or greater than 9007198180999168.	400	Bad Request
182	Invalid MemoryRequest setting. The MemoryRequest setting may not exceed the Scheduler.MaxMemoryRequest setting.	400	Bad Request
183	Invalid MemoryLimit setting. The MemoryLimit setting cannot be less than 0 or greater than 9007198180999168.	400	Bad Request
184	Invalid MemoryLimit setting. The MemoryLimit setting may not exceed the Scheduler.MaxMemoryLimit setting.	400	Bad Request
185	Invalid MemoryRequest setting. The MemoryRequest setting may not exceed the MemoryLimit setting.	400	Bad Request
186	Invalid CPURequest setting. The CPURequest setting must be a positive number.	400	Bad Request
187	Invalid CPURequest setting. The CPURequest setting may not exceed the Scheduler.MaxCPURequest setting.	400	Bad Request
188	Invalid CPULimit setting. The CPULimit setting must be a positive number.	400	Bad Request
189	Invalid CPULimit setting. The CPULimit setting may not exceed the Scheduler.MaxCPULimit setting.	400	Bad Request
190	Invalid CPURequest setting. The CPURequest setting may not exceed the CPULimit setting.	400	Bad Request
191	Invalid MinProcesses setting. The MinProcesses setting must be a positive number.	400	Bad Request
192	Invalid MaxProcesses setting. The MaxProcesses setting must be a positive number.	400	Bad Request
193	When provided, the default_image_name cannot be empty and may not contain any whitespace characters.	400	Bad Request
194	Runtime cache management is disabled.	400	Bad Request
195	Invalid configuration. Service accounts cannot be set on content. Please contact an administrator to update Connect’s server configuration to enable this feature.	400	Bad Request
196	Invalid AMDGPULimit setting. The AMDGPULimit setting cannot be less than 0.	400	Bad Request
197	Invalid AMDGPULimit setting. The AMDGPULimit setting may not exceed the Scheduler.MaxAMDGPULimit setting.	400	Bad Request
198	Invalid NvidiaGPULimit setting. The NvidiaGPULimit setting cannot be less than 0.	400	Bad Request
199	Invalid NvidiaGPULimit setting. The NvidiaGPULimit setting may not exceed the Scheduler.MaxNvidiaGPULimit setting.	400	Bad Request
200	No valid recipients.	400	Bad Request
201	Invalid default OAuth scope.	400	Bad Request
202	Invalid default OAuth scopes. The number of default scopes cannot be greater than 1024.	400	Bad Request
203	OAuth client id must be between 1 and 1024 characters.	400	Bad Request
204	OAuth tenant id must be between 1 and 1024 characters.	400	Bad Request
205	OAuth client secret must be between 1 and 1024 characters.	400	Bad Request
206	OAuth description must be between 1 and 1024 characters.	400	Bad Request
207	Invalid OAuth integration GUID. Submitted GUIDs must represent a valid OAuth integration.	400	Bad Request
208	Invalid OAuth integrations.	400	Bad Request
209	Invalid OAuth association assignment. OAuth associations cannot be assigned to static content types.	400	Bad Request
210	Form-post not found in request.	400	Bad Request
211	Unable to parse form-post from request.	400	Bad Request
212	No OAuth integrations have been associated with this content item.	400	Bad Request
213	Invalid grant_type. Expected ‘urn:ietf:params:oauth:grant-type:token-exchange’	400	Bad Request
214	Invalid subject_token_type. Expected ‘urn:posit:connect:user-session-token’ or ‘urn:posit:connect:content-session-token’	400	Bad Request
215	Invalid subject_token.	400	Bad Request
216	Iss claim must match the server address.	400	Bad Request
217	Sub claim must be a valid GUID.	400	Bad Request
218	Invalid OAuth session. No refresh token found.	400	Bad Request
219	Failed to refresh OAuth Access Token.	400	Bad Request
220	No OAuth session found. Log in to the OAuth Integration before requesting credentials.	404	Not Found
221	OAuth integrations are not permitted by your license.	402	Payment Required
222	Cannot deploy or update bundles for locked content.	403	Forbidden
223	Cannot start new processes for locked content.	403	Forbidden
224	Locked message must be less than 4096 alphanumeric characters.	400	Bad Request
225	Invalid OAuth integration name. Name must be a single line string.	400	Bad Request
226	Invalid OAuth integration description. Description must be a single line string and cannot be longer than 4096 characters.	400	Bad Request
227	OAuth template not found.	404	Not Found
228	OAuth template configuration invalid.	400	Bad Request
229	OAuth template cannot be changed.	400	Bad Request
230	Invalid OAuth integration login request.	400	Bad Request
231	No content.	204	No Content
232	The URL provided to download a bundle for a given content item is not valid.	400	Bad Request
233	Unable to fetch the bundle from the URL provided.	500	Internal Server Error
234	You don’t have permission to give the key this role.	403	Forbidden
235	Invalid OAuth refresh token. Log in to the integration again to acquire a new refresh token.	400	Bad Request
236	Invalid ‘urn:posit:connect:content-session-token’	403	Forbidden
237	Invalid OAuth association auth type. Rendered or public content cannot be associated with a ‘Viewer’ OAuth integration.	400	Bad Request
238	Session token auth flow type does not match associated integration.	400	Bad Request
239	Invalid MaxConnsPerProcess setting. The MaxConnsPerProcess setting must be greater than 0.	400	Bad Request
240	Invalid OAuth service account integration test auth type. Cannot test ‘Viewer’ OAuth integrations, only ‘Service Account’ OAuth integrations.	400	Bad Request
241	Unable to retrieve OAuth token for integration.	400	Bad Request
242	Invalid requested_token_type.	400	Bad Request
243	API Key integration must have exactly one scope defined.	400	Bad Request
244	Invalid maximum authorization role value for API Key integration.	400	Bad Request
245	Invalid schedule.	400	Bad Request
246	Invalid execution environment permission.	400	Bad Request
247	Duplicate execution environment permission.	409	Conflict
248	Unable to retrieve AWS credentials for the specified AWS integration.	500	Internal Server Error
249	Invalid subject_token_type and requested_token_type combination.	400	Bad Request
250	No supported handler for the specified subject_token_type and requested_token_type combination.	400	Bad Request
251	Missing ID token. Ensure the integration is configured to use the ‘openid’ scope.	400	Bad Request
252	Invalid subject_token_type for the integration’s specified auth_type.	400	Bad Request
253	RunAs customization is disabled.	400	Bad Request
254	Invalid volume attributes.	400	Bad Request
255	Custom documentation maximum length is 500000 characters.	400	Bad Request
256	Invalid audience. The audience must be a valid integration GUID that is associated with your content.	400	Bad Request
257	Invalid association count. The number of OAuth associations must be exactly one when the audience is not provided in the credential exchange request.	400	Bad Request
258	Invalid OAuth integrations. There must be no duplicate OAuth integrations in the request.	400	Bad Request
259	Only public interactive content can be checked for access.	400	Bad Request
260	Public access is not permitted by your license.	403	Forbidden
261	Invalid user GUID. Submitted GUIDs must represent a valid user.	400	Bad Request
262	Invalid group GUID. Submitted GUIDs must represent a valid group.	400	Bad Request
263	The requested group GID is already in use.	409	Conflict
264	The email address format is invalid.	400	Bad Request
265	This execution environment is managed by a configuration file and cannot be modified via the API.	409	Conflict
266	Environment variable name cannot be empty.	400	Bad Request
267	The content is already bookmarked.	409	Conflict
268	First name cannot be more than 256 characters.	400	Bad Request
269	Last name cannot be more than 256 characters.	400	Bad Request
270	Node.js content requires the Advanced license tier.	403	Forbidden

API Keys

List API keys

GET /v1/users/{guid}/keys

List your provisioned API keys.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

Object containing API key details.

Name	Type	Description
id	string	The unique identifier for this API key. Example: 2.
name	string	The name for this API key. The name often describes the purpose of the key. Example: Automation.
key	string	The secret text for this API key. The full key is only revealed when the key is created. Subsequent reads only reveal the last few characters. Example: abcdefgabcdefg.
user_role	string	The role of this API key. Enum: administrator, publisher, viewer. Example: viewer.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when the key was created. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the key was last used. Highly active keys only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create an API key

POST /v1/users/{guid}/keys

Create an API key.

Users can only create API keys for themselves. If guid does not match the current user’s GUID, a 403 status is returned.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

An object sent to create an API key.

Name	Type	Description
name	string	The name for this API key. Use the name to describe the purpose of the key. Example: Automation.
user_role	string	The role of this API key. Cannot be greater than the role of the user account. Defaults to the user account role when null. Enum: administrator, publisher, viewer. Example: viewer.

Responses

200

200: Successful response.

Object containing API key details.

Name	Type	Description
id	string	The unique identifier for this API key. Example: 2.
name	string	The name for this API key. The name often describes the purpose of the key. Example: Automation.
key	string	The secret text for this API key. The full key is only revealed when the key is created. Subsequent reads only reveal the last few characters. Example: abcdefgabcdefg.
user_role	string	The role of this API key. Enum: administrator, publisher, viewer. Example: viewer.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when the key was created. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the key was last used. Highly active keys only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get an API key

GET /v1/users/{guid}/keys/{id}

Get details for a single API key.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

200

200: Successful response.

Object containing API key details.

Name	Type	Description
id	string	The unique identifier for this API key. Example: 2.
name	string	The name for this API key. The name often describes the purpose of the key. Example: Automation.
key	string	The secret text for this API key. The full key is only revealed when the key is created. Subsequent reads only reveal the last few characters. Example: abcdefgabcdefg.
user_role	string	The role of this API key. Enum: administrator, publisher, viewer. Example: viewer.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when the key was created. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the key was last used. Highly active keys only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete an API key

DELETE /v1/users/{guid}/keys/{id}

Delete a single API key.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Audit Logs

Get audit logs

GET /v1/audit_logs

This endpoint returns a portion of the audit logs, as well as paging information that can be used to navigate the audit log results.

This endpoint requires administrator access.

This endpoint uses keyset pagination. The URLs in the paging field’s subfields can be used to fetch the next, previous, first, and last pages of results.

Parameters

Name	Type	Description
limit	integer	Number of logs to return. The minimum supported value is 1 and maximum supported value is 500. Note that limit is a “best effort” request since there may not be enough logs to satisfy the limit.
previous	string	Gets the previous page of audit logs relative to the given id.
next	string	Gets the next page of audit logs relative to the given id.
ascOrder	boolean	Whether the audit logs should be listed in ascending order.

Responses

200

200: Successful response.

Audit log results with keyset pagination.

Name	Type	Description
results	[object]	The audit logs
results[].id	string	The identifier of the audit action.
results[].time	string (date-time)	Timestamp in RFC3339 format when the action was taken. Example: 2006-01-02T15:04:05-07:00.
results[].user_id	string	The user identifier of the actor who performed the audit action.
results[].user_guid	string (uuid)|null	The user GUID of the actor who performed the audit action.
results[].user_description	string	A description of the actor. Example: Full name (username).
results[].action	string	The audit action taken. Example: add_user.
results[].event_description	string	A human-readable description of the action. Example: Added user Full Name (username).
paging	object	Paging object that can be used for navigation.
paging.first	string|null	A full URL of the first page of results. Null if the current response is the first page.
paging.previous	string|null	A full URL of the previous page of results. Null if the current response is the first page.
paging.next	string|null	A full URL of the next page of results. Null if the current response is the last page.
paging.last	string|null	A full URL of the last page of results. Null if the current response is the last page.
paging.cursors	object	Cursor values for navigating between pages.
paging.cursors.previous	string|null	A cursor ID that can be used with the previous query parameter to get the previous page of results. Example: 23948901087.
paging.cursors.next	string|null	A cursor ID that can be used with the next query parameter to get the next page of results. Example: 23948901087.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get audit actions

GET /v1/audit/actions

Retrieve the list of audit actions available on your Posit Connect server. You can also see a list of these actions in the Admin Guide. Action names can be used to filter audit logs in the Audit Log Search API.

Responses

200

200: Successful response.

Array of objects:

An audit action available on your Posit Connect server.

Name	Type	Description
action	string	The name of the action. Example: create_user.
description	string	A human-readable description of the action. Example: Create a new user..

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Search audit logs

GET /v1/search/auditlogs

This endpoint searches for audit logs, using a search query format that allows for both search terms and filters. The search terms are used to find audit logs that have matching terms in the audit action, audit description, etc, while the filters are used to filter the search results by specific fields (such as user_guid or the audit time).

Authenticated access with an Administrator role is required.

Search query

The search query is a string that includes both search terms and filters. Any text in the search query that is not a supported filter is treated as a search term, and those search terms are matched against any of: user_description, action, or event_description. Note that the search terms are case-insensitive, and all terms must be present in an audit log entry for it to be included in the search results.

Filters

Filters are specified as colon-delimited key-value pairs, containing one or more values separated by commas. If any of the values within a filter contain a space or comma, you should use quotes around the value. Example:

myterm tag:tagwithoutspace,"tag with space"

You can negate a filter or search term by prefixing it with a -. For example, -user_id:0 will exclude audit logs produced by system actors which have a default user_id of 0.

The following filters are supported:

action:<action>[,<additional-actions>,...] - Only return audit logs that have the specified action. If more than one action is provided, audit logs with ANY of the specified actions will be included. Note that actions are not case sensitive. Audit actions are enumerated in the Admin Guide, and are also exposed in the GET /v1/audit/actions.

user_guid:<user_guid>[,<additional-user_guids>,...] - Only return audit logs that have the specified user GUID. If more than one user GUID is provided, audit logs with ANY of the specified user GUIDs will be included.

user_id:<user_id>[,<additional-user_ids>,...] - Only return audit logs that have the specified user ID. If more than one user ID is provided, audit logs with ANY of the specified user IDs will be included. The user ID 0 is reserved for system actors.

from:<timestamp> - Only return audit logs that have a timestamp greater than or equal to the specified timestamp. The timestamp must be provided in RFC3339 format, such as 2023-01-01T12:34:56Z. Up to nanosecond precision is supported (e.g. 2023-01-01T12:34:56.123456789Z). The timestamp is inclusive, so audit logs with the specified timestamp will be included in the results.

to:<timestamp> - Only return audit logs that have a timestamp less than or equal to the specified timestamp. The timestamp must be provided in RFC3339 format, such as 2023-01-01T12:34:56Z. Up to nanosecond precision is supported (e.g. 2023-01-01T12:34:56.123456789Z). The timestamp is inclusive, so audit logs with the specified timestamp will be included in the results.

Pagination

This endpoint uses offset pagination. Requests can include query-string parameters for page_number and page_size to fetch different pages of results.

Parameters

Name	Type	Description
q	string	Search audit log entries.
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
order	string	The sort order: asc or desc.

Responses

200

200: Successful response.

Audit log search results with total count.

Name	Type	Description
total	integer	The total number of matching audit log entries. Example: 100.
results	[object]	The matching audit log entries for this page.
results[].id	string	The unique identifier of the audit log entry. Example: 123.
results[].time	string (date-time)	The timestamp (RFC3339) of the audit action. Example: 2006-01-02T15:04:05-07:00.
results[].user_id	string	The unique identifier of the user who performed the action. Example: 456.
results[].user_guid	string (uuid)|null	The GUID of the user who performed the action. Example: d4aaf24e-b7d5-404f-843e-a78e4c1eab38.
results[].user_description	string	A description of the user who performed the action. Example: John Doe.
results[].action	string	The name of the audit action. Example: create_user.
results[].event_description	string	A human-readable description of the event. Example: Created a new user account..

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Bookmarks

Get bookmark

GET /v1/content/{guid}/bookmark

Get the bookmark for this content item for the requesting user. Returns a bookmark record if the user has bookmarked this content, and a 404 status otherwise. Authenticated access is required. The user must have permission to view the content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

The fields that are returned when getting a bookmark.

Name	Type	Description
created_time	string (date-time)	The timestamp (RFC3339) indicating when this bookmark was created. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create bookmark

POST /v1/content/{guid}/bookmark

Create a bookmark for this content item for the requesting user. A bookmark allows the user to save content for quick access later. Each user can only have one bookmark per content item. Authenticated access is required. The user must have permission to view the content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

201

201: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete bookmark

DELETE /v1/content/{guid}/bookmark

Delete the bookmark for this content item for the requesting user. Authenticated access is required. The user must have permission to view the content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Bootstrap

Create first administrator and API key

POST /v1/bootstrap

This endpoint creates an initial administrator user, provisions an API key for the initial administrator, and returns the API key. This endpoint only functions for installations with no pre-existing users.

Code samples

curl

#!/bin/bash

BOOTSTRAP_JWT="your.jwt.here"

curl --silent --show-error -L --max-redirs 0 --fail \
    -X POST \
    -H "Authorization: Connect-Bootstrap ${BOOTSTRAP_JWT}" \
    "https://connect.example.com/__api__/v1/bootstrap"

Python

import requests

bootstrap_jwt = "your.jwt.here"
headers = { 'Authorization': 'Connect-Bootstrap ' + bootstrap_jwt }

response = requests.post("https://connect.example.com/__api__/v1/bootstrap",
    headers=headers)

R

library(httr)

bootstrapJwt <- "your.jwt.here"

result <- POST("https://connect.example.com/__api__/v1/bootstrap",
    add_headers(Authorization = paste("Connect-Bootstrap", bootstrapJwt)))

Responses

200

200: Successful response.

Name	Type	Description
api_key	string	The API key for the newly created administrator user.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create first administrator and API key

POST /v1/experimental/bootstrap

Warning

This endpoint is deprecated.

This endpoint creates an initial administrator user, provisions an API key for the initial administrator, and returns the API key. This endpoint only functions for installations with no pre-existing users.

This endpoint is deprecated. Use POST /v1/bootstrap instead.

Responses

200

200: Successful response.

Name	Type	Description
api_key	string	The API key for the newly created administrator user.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Bundles

List bundles

GET /v1/content/{guid}/bundles

List bundles associated with a specific content item.

Bundle enumeration is permitted by all users with viewership rights to the content item and administrators. Information about the target environment is populated for users with “publisher” and “administrator” role.

Results are sorted by ID.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

A deployment bundle associated with a content item.

Name	Type	Description
id	string	The identifier for this bundle. Example: 101.
content_guid	string (uuid)	The identifier of the owning content. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_by	string (uuid)|null	The GUID of the user who created the bundle.
created_time	string (date-time)	The timestamp (RFC3339) of when this bundle was created. Example: 2006-01-02T15:04:05-07:00.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The version of R used when last restoring this bundle. A null value represents that R is not used by this bundle or that the bundle has not been prepared for execution. R version is not disclosed to users with a “viewer” role; they receive a null value. Example: 3.5.1.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. The null value represents that R is not used by this bundle or that it has not yet been determined if an R environment is required. R environment management is not disclosed to users with a “viewer” role; they receive a null value. Example: true.
py_version	string|null	The version of Python used when last restoring this bundle. A null value represents that Python is not used by this bundle or that the bundle has not been prepared for execution. Python version is not disclosed to users with a “viewer” role; they receive a null value. Example: 3.8.2.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. The null value represents that Python is not used by this bundle or that it has not yet been determined if a Python environment is required. Python environment management is not disclosed to users with a “viewer” role; they receive a null value. Example: true.
quarto_version	string|null	The version of Quarto used when last restoring this bundle. A null value represents that Quarto is not used by this bundle or that the bundle has not been successfully prepared for execution. Quarto version is not disclosed to users with a “viewer” role; they receive a null value. Example: 0.2.22.
active	boolean	Indicates if this bundle is active for the owning content. Example: false.
size	integer	On-disk size in bytes of the tar.gz file associated with this bundle. Zero when there is no on-disk file. Example: 1000000.
metadata	object	Metadata object associated with this bundle. May be generated by Connect, if using git-backed publishing, or supplied by the publisher at upload time.
metadata.source	string|null	Source for this bundle. git for bundles fetched from a git repository.
metadata.source_repo	string|null	Repository URL for this bundle.
metadata.source_branch	string|null	Repository branch or ref name for this bundle.
metadata.source_commit	string|null	Commit ID (hash) for this bundle.
metadata.archive_md5	string|null	MD5 hash of the archive file for this bundle. null for bundles uploaded before this field was added. Example: 37324238a80595c453c706b22adb83d3.
metadata.archive_sha1	string|null	SHA1 hash of the archive file for this bundle. null for bundles uploaded before this field was added. Example: a2f7d13d87657df599aeeabdb70194d508cfa92f.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create a bundle by uploading an archive

POST /v1/content/{guid}/bundles

Create a new deployment bundle by uploading an archive.

Upload a compressed tar archive containing code/data that represent one deployment of this content. Bundles must be gzip compressed tar archives.

• All deployment bundles include a manifest.json describing the contained files and their runtime dependencies.
• A bundle for a Shiny application includes an app.R or ui.R and server.R, and any images or data files required by the application.
• Python API and application bundles include the application source code, typically named app.py, and a list of required package dependencies in requirements.txt.
• An R Markdown document bundle includes the index.Rmd file along with any R scripts and data files needed to render the report.
• A Quarto bundle includes at least one .qmd file, along with any auxiliary files required. Quarto projects include a _quarto.yml file.
• Bundles containing HTML content should include any CSS, Javascript, and images required by that document.

The manifest.json file and primary source files like app.R, app.py, or index.Rmd must be in the top level of the archived directory. Subdirectories may be used for secondary data and scripts.

Here is how you might use tar to create an archive for a Shiny application. It includes the manifest, the application, and an image.

tar zcf bundle.tar.gz ./manifest.json ./app.R ./www/logo.png

You could create a bundle for a Python application similarly:

tar zcf bundle.tar.gz ./manifest.json ./app.py ./requirements.txt ./www/logo.png

Here is another example of creating a bundle for an application but from its parent directory. The application is in a sales-analyzer sub-directory. This command will include all files in the subdirectory; check to ensure that this does not include extraneous files such as output files or local Python environments that you do not want in the bundle.

tar zcf bundle.tar.gz ./sales-analyzer

Publishers with collaborator rights to this content (including the owner) are permitted to upload deployment bundles. Users without these rights are rejected.

Administrators must be a collaborator for a content item before they receive upload rights.

Upload formats

This endpoint supports two upload methods.

You can send the bundle archive directly as the request body with Content-Type: application/gzip or application/x-gzip:

curl -X POST \
  -H "Authorization: Key ${API_KEY}" \
  -H "Content-Type: application/gzip" \
  --data-binary @bundle.tar.gz \
  "https://connect.example.com/__api__/v1/content/${GUID}/bundles"

Or, you can send the bundle as a multipart form and include a JSON object of metadata. This allows you to include source control information and other arbitrary fields.

curl -X POST \
  -H "Authorization: Key ${API_KEY}" \
  -F "archive=@bundle.tar.gz" \
  -F 'metadata={"source":"git","source_repo":"https://github.com/org/repo","source_branch":"main","source_commit":"abc123"};type=application/json' \
  "https://connect.example.com/__api__/v1/content/${GUID}/bundles"

You can also use multipart form to provide a URL to fetch the bundle from, along with metadata:

curl -X POST \
  -H "Authorization: Key ${API_KEY}" \
  -F "url=https://content-library.com/bundles/bundle.tar.gz" \
  -F 'metadata={"source":"git","source_repo":"https://github.com/org/repo","source_branch":"main","source_commit":"abc123"};type=application/json' \
  "https://connect.example.com/__api__/v1/content/${GUID}/bundles"

The metadata form field is optional and accepts a JSON object string. Some fields are known to Connect and used in the application:

• source - Source system identifier (e.g., “git”, “github-actions”, “gitlab-ci”)
• source_repo - Repository URL
• source_branch - Branch or reference name
• source_commit - Commit hash or identifier

Additional custom fields are accepted. Field values are stored as strings; non-string values will be serialized to JSON.

Code samples

curl

Binary upload

API_KEY="your api key"
FILENAME="archive.tar.gz"

curl --silent --show-error -L --max-redirs 0 --fail \
    -X POST \
    -H "Authorization: Key ${API_KEY}" \
    -H "Content-Type: application/gzip" \
    --data-binary @"${FILENAME}" \
    "https://connect.example.com/__api__/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles"

Multipart upload with metadata

API_KEY="your api key"
FILENAME="archive.tar.gz"

curl --silent --show-error -L --max-redirs 0 --fail \
    -X POST \
    -H "Authorization: Key ${API_KEY}" \
    -F 'metadata={"source":"git","source_repo":"https://github.com/org/repo","source_branch":"main","source_commit":"abc123def456"};type=application/json' \
    -F "archive=@${FILENAME}" \
    "https://connect.example.com/__api__/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles"

Multipart upload with URL and metadata

API_KEY="your api key"

curl --silent --show-error -L --max-redirs 0 --fail \
    -X POST \
    -H "Authorization: Key ${API_KEY}" \
    -F "url=https://content-library.com/bundles/bundle.tar.gz" \
    -F 'metadata={"source":"git","source_repo":"https://github.com/org/repo","source_branch":"main","source_commit":"abc123def456"};type=application/json' \
    "https://connect.example.com/__api__/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles"

Python

Binary upload

from posit import connect

# Assumes CONNECT_SERVER and CONNECT_API_KEY are set in the environment

client = connect.Client()
filename = "archive.tar.gz"

with open(filename, "rb") as f:
    response = client.post("/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles",
        data=f)

Multipart upload with metadata

import requests
import json

# Assumes CONNECT_SERVER and CONNECT_API_KEY are set in the environment

api_key = "your api key"
filename = "archive.tar.gz"

metadata = {
    "source": "git",
    "source_repo": "https://github.com/org/repo",
    "source_branch": "main",
    "source_commit": "abc123def456"
}

with open(filename, "rb") as f:
    # Fields can be provided in any order
    files = [
        ("metadata", (None, json.dumps(metadata), "application/json")),
        ("archive", f)
    ]
    response = requests.post(
        "https://connect.example.com/__api__/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles",
        headers={"Authorization": f"Key {api_key}"},
        files=files
    )

Multipart upload with URL and metadata

import requests
import json

# Assumes CONNECT_SERVER and CONNECT_API_KEY are set in the environment

api_key = "your api key"

metadata = {
    "source": "git",
    "source_repo": "https://github.com/org/repo",
    "source_branch": "main",
    "source_commit": "abc123def456"
}

# Fields can be provided in any order
files = [
    ("metadata", (None, json.dumps(metadata), "application/json")),
    ("url", (None, "https://content-library.com/bundles/bundle.tar.gz", "text/plain"))
]
response = requests.post(
    "https://connect.example.com/__api__/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles",
    headers={"Authorization": f"Key {api_key}"},
    files=files
)

R

Binary upload

library(connectapi)

# Assumes CONNECT_SERVER and CONNECT_API_KEY are set in the environment

client <- connect()
filename <- "archive.tar.gz"
result <- client$POST("/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles",
    body = upload_file(filename))

Multipart upload with metadata

library(httr)
library(jsonlite)

# Assumes CONNECT_SERVER and CONNECT_API_KEY are set in the environment

api_key <- Sys.getenv("CONNECT_API_KEY")
server <- Sys.getenv("CONNECT_SERVER")
filename <- "archive.tar.gz"

metadata <- list(
    source = "git",
    source_repo = "https://github.com/org/repo",
    source_branch = "main",
    source_commit = "abc123def456"
)

# Fields can be provided in any order
result <- POST(
    paste0(server, "/__api__/v1/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/bundles"),
    add_headers(Authorization = paste("Key", api_key)),
    body = list(
        metadata = toJSON(metadata, auto_unbox = TRUE),
        archive = upload_file(filename)
    )
)

Parameters

Path parameters

Name	Type	Description
guid	string (uuid)	Required.

Query parameters

Name	Type	Description
url	string	URL of a gzip compressed tar archive.

Header parameters

Name	Type	Description
X-Content-Checksum	string	The Base64-encoded MD5 sum of the archive file.

Request body

application/gzip

string (binary)

application/x-gzip

string (binary)

multipart/form-data

Name	Type	Description
archive	string (binary)	A gzip compressed tar archive file.
metadata	string	Optional JSON object containing metadata about this bundle.
url	string	URL of a gzip compressed tar archive. Either archive or url must be provided.

Responses

200

200: Successful response.

A deployment bundle associated with a content item.

Name	Type	Description
id	string	The identifier for this bundle. Example: 101.
content_guid	string (uuid)	The identifier of the owning content. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_by	string (uuid)|null	The GUID of the user who created the bundle.
created_time	string (date-time)	The timestamp (RFC3339) of when this bundle was created. Example: 2006-01-02T15:04:05-07:00.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The version of R used when last restoring this bundle. A null value represents that R is not used by this bundle or that the bundle has not been prepared for execution. R version is not disclosed to users with a “viewer” role; they receive a null value. Example: 3.5.1.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. The null value represents that R is not used by this bundle or that it has not yet been determined if an R environment is required. R environment management is not disclosed to users with a “viewer” role; they receive a null value. Example: true.
py_version	string|null	The version of Python used when last restoring this bundle. A null value represents that Python is not used by this bundle or that the bundle has not been prepared for execution. Python version is not disclosed to users with a “viewer” role; they receive a null value. Example: 3.8.2.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. The null value represents that Python is not used by this bundle or that it has not yet been determined if a Python environment is required. Python environment management is not disclosed to users with a “viewer” role; they receive a null value. Example: true.
quarto_version	string|null	The version of Quarto used when last restoring this bundle. A null value represents that Quarto is not used by this bundle or that the bundle has not been successfully prepared for execution. Quarto version is not disclosed to users with a “viewer” role; they receive a null value. Example: 0.2.22.
active	boolean	Indicates if this bundle is active for the owning content. Example: false.
size	integer	On-disk size in bytes of the tar.gz file associated with this bundle. Zero when there is no on-disk file. Example: 1000000.
metadata	object	Metadata object associated with this bundle. May be generated by Connect, if using git-backed publishing, or supplied by the publisher at upload time.
metadata.source	string|null	Source for this bundle. git for bundles fetched from a git repository.
metadata.source_repo	string|null	Repository URL for this bundle.
metadata.source_branch	string|null	Repository branch or ref name for this bundle.
metadata.source_commit	string|null	Commit ID (hash) for this bundle.
metadata.archive_md5	string|null	MD5 hash of the archive file for this bundle. null for bundles uploaded before this field was added. Example: 37324238a80595c453c706b22adb83d3.
metadata.archive_sha1	string|null	SHA1 hash of the archive file for this bundle. null for bundles uploaded before this field was added. Example: a2f7d13d87657df599aeeabdb70194d508cfa92f.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get bundle details

GET /v1/content/{guid}/bundles/{id}

Get detailed information about a specific bundle.

Bundle reads are permitted by all users with viewership rights to the content item and administrators. Information about the target environment is populated for users with “publisher” and “administrator” role.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

200

200: Successful response.

A deployment bundle associated with a content item.

Name	Type	Description
id	string	The identifier for this bundle. Example: 101.
content_guid	string (uuid)	The identifier of the owning content. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_by	string (uuid)|null	The GUID of the user who created the bundle.
created_time	string (date-time)	The timestamp (RFC3339) of when this bundle was created. Example: 2006-01-02T15:04:05-07:00.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The version of R used when last restoring this bundle. A null value represents that R is not used by this bundle or that the bundle has not been prepared for execution. R version is not disclosed to users with a “viewer” role; they receive a null value. Example: 3.5.1.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. The null value represents that R is not used by this bundle or that it has not yet been determined if an R environment is required. R environment management is not disclosed to users with a “viewer” role; they receive a null value. Example: true.
py_version	string|null	The version of Python used when last restoring this bundle. A null value represents that Python is not used by this bundle or that the bundle has not been prepared for execution. Python version is not disclosed to users with a “viewer” role; they receive a null value. Example: 3.8.2.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. The null value represents that Python is not used by this bundle or that it has not yet been determined if a Python environment is required. Python environment management is not disclosed to users with a “viewer” role; they receive a null value. Example: true.
quarto_version	string|null	The version of Quarto used when last restoring this bundle. A null value represents that Quarto is not used by this bundle or that the bundle has not been successfully prepared for execution. Quarto version is not disclosed to users with a “viewer” role; they receive a null value. Example: 0.2.22.
active	boolean	Indicates if this bundle is active for the owning content. Example: false.
size	integer	On-disk size in bytes of the tar.gz file associated with this bundle. Zero when there is no on-disk file. Example: 1000000.
metadata	object	Metadata object associated with this bundle. May be generated by Connect, if using git-backed publishing, or supplied by the publisher at upload time.
metadata.source	string|null	Source for this bundle. git for bundles fetched from a git repository.
metadata.source_repo	string|null	Repository URL for this bundle.
metadata.source_branch	string|null	Repository branch or ref name for this bundle.
metadata.source_commit	string|null	Commit ID (hash) for this bundle.
metadata.archive_md5	string|null	MD5 hash of the archive file for this bundle. null for bundles uploaded before this field was added. Example: 37324238a80595c453c706b22adb83d3.
metadata.archive_sha1	string|null	SHA1 hash of the archive file for this bundle. null for bundles uploaded before this field was added. Example: a2f7d13d87657df599aeeabdb70194d508cfa92f.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete bundle

DELETE /v1/content/{guid}/bundles/{id}

Delete a specific bundle.

Bundle deletion is permitted by authorized clients with collaborator rights and administrators.

On-disk data and database records are removed as a consequence of this call. Deletion is not allowed while the bundle is still active.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Download the bundle archive

GET /v1/content/{guid}/bundles/{id}/download

Download a deployment bundle.

Bundle download is permitted by authorized clients with collaborator rights.

Download a gzip compressed tar archive (.tar.gz) containing the code/data from one deployment of the associated content.

See the POST /v1/content/{guid}/bundles endpoint for details about the construction of bundle archives.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Content

List content items

GET /v1/content

List all content items visible to the requesting user.

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.

Information about the target environment is populated for users with “publisher” and “administrator” role; it is suppressed for viewers.

Parameters

Name	Type	Description
name	string	The content name specified when the content was created. Content names are unique within the owning user’s account, so a request that specifies a non-empty name and owner_guid will return at most one content item.
owner_guid	string	The unique identifier of the user who owns the content.
include	string	Comma-separated set of values indicating additional details to include in the response. tags: Populates a tags field for each returned content item containing the tags associated with this content item. owner: Populates an owner field for each returned content item with basic details about the content owner. vanity_url: Populates the vanity_url field for each returned content item if the content has an associated custom vanity URL. bookmarked: Populates a bookmarked field for each returned content item indicating whether the requesting user has bookmarked the content. schedule: Populates a schedules field for each returned content item with the list of schedules associated with the content, including variant details and last run information.

Responses

200

200: Successful response.

Array of objects:

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.

Name guid	Type string (uuid)	Description The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
access_type	string	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.
locked	boolean	Whether or not the content is locked. Example: false.
locked_message	string	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.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. If the process tries to use more memory than allowed, it will be terminated. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration. If the process tries to use more CPU than allowed, it will be throttled. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.AMDGPULimit is used. This setting can not exceed Scheduler.MaxAMDGPULimit. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.NvidiaGPULimit is used. This setting can not exceed Scheduler.MaxNvidiaGPULimit. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account that is used to run a particular piece of content. It must adhere to valid Kubernetes service account naming rules. Connect must be configured to run with Launcher.Enabled = true, Launcher.Kubernetes = true and Launcher.KubernetesContentServiceAccountSelection = true for this value to be applied. It will have precedence over the Launcher.KubernetesDefaultServiceAccount that may be set in the configuration for Connect. If this value is defined and Connect is configured with Launcher.KubernetesContentServiceAccountSelection = false an error will be returned. Only administrators and publishers can view this value. Only administrators can set or change this value. Example: rstudio-connect-content.
default_image_name	string|null	The default image that will be used when none is defined by the bundle’s manifest. A specific image may be selected by setting the environment.image field in the manifest. If no image is selected by the manifest file, then the default_image_name is used. If a target image is not defined by the manifest, and no default_image_name is configured, then Connect will select an image from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment that will be used when none is defined by the bundle’s manifest. A specific execution environment may be selected by setting the environment.identifier field in the manifest. If no execution environment is selected by the manifest file, then default_environment_guid is used to select the execution environment. If a target execution environment is not defined by the manifest, and no default_environment_guid is configured, then Connect will select an execution environment from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this content was created. Example: 2006-01-02T15:04:05-07:00.
last_deployed_time	string (date-time)	The timestamp (RFC3339) indicating when this content last had a successful bundle deployment performed. Example: 2006-01-02T15:04:05-07:00.
bundle_id	string|null	The identifier for the active deployment bundle. Automatically assigned upon the successful deployment of that bundle. Example: 101.
app_mode	string	The runtime model for this content. Has a value of unknown before data is deployed to this item. Automatically assigned upon the first successful bundle deployment. Valid values are: api - R code defining a Plumber API. jupyter-static - A Jupyter Notebook. jupyter-voila A Voila interactive dashboard. python-api - Python code defining a WSGI API (such as Flask) python-bokeh - Python code defining a Bokeh application. python-panel - Python code defining a Panel application. python-dash - Python code defining a Dash application. python-fastapi - Python code defining an ASGI API (such as FastAPI) python-gradio - Python code defining a Gradio application. python-shiny - Python code defining a Shiny application. python-streamlit - Python code defining a Streamlit application. quarto-shiny - A Quarto document with a Shiny runtime. quarto-static - A Quarto document or site. rmd-shiny - An R Markdown document with a Shiny runtime. rmd-static - An R Markdown document or site. shiny - R code defining a Shiny application. static - Content deployed without source; often HTML and plots. tensorflow-saved-model - A TensorFlow Model API. unknown - No known runtime model. Example: shiny.
content_category	string	Describes the specialization of the content runtime model. | Automatically assigned upon the first successful bundle deployment. | | The content_category field refines the type of content specified by | app_mode. It is empty by default. The rsconnect R package may assign | a value when analyzing your content and building its manifest and | bundle. Plots (images created in the RStudio IDE and presented in the | “Plots” pane) have an app_mode of static and receive a | content_category of plot to distinguish them from other HTML | documents. Pinned static data sets have an app_mode of static and a | content_category of pin. Multi-document R Markdown sites have an | app_mode of rmd-static and a content_category of site. | API content types (such as FastAPI, Flask, or Plumber) that serve as | MCP servers have a content_category of mcp. The mcp category is | auto-detected on first deploy but can also be set or cleared via | PATCH /v1/content/{guid}. | | Example: site. |
parameterized	boolean	True when R Markdown rendered content allows parameter configuration. Automatically assigned upon the first successful bundle deployment. Applies only to content with an app_mode of rmd-static. Example: false.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have either a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The of R interpreter associated with this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.5.1.
py_version	string|null	The version of Python associated with this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.8.2.
quarto_version	string|null	The version of Quarto associated with this content. A null represents that Quarto is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 0.2.22.
node_version	string|null	The version of Node.js associated with this content. A null represents that Node.js is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 22.11.0.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Only administrators can change this value. If Applications.RunAsEnabled = false, this value will be ignored when executing content. Example: rstudio-connect.
run_as_current_user	boolean	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Connect must be configured to use PAM authentication with the server settings Applications.RunAsCurrentUser = true and PAM.ForwardPassword = true. This setting has no effect for other authentication types. This setting only applies to application content types (Shiny, Dash, Streamlit, Bokeh, and Panel). Only administrators can change this value. Example: false.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics (CPU, memory, connections) | are collected for this content item. | | When null, the content item inherits the server-wide default from | Applications.MetricsCollectionEnabled. Explicit true or false | values override the server default. | | Metrics can be retrieved via the | GET /v1/content/{guid}/jobs/{key}/metrics endpoint. | Example: true. |
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, the content item inherits the server-wide default from Applications.NotifyOnShare. Explicit true or false values override the server default. Example: true.
trace_collection_enabled	boolean	Whether per-job OpenTelemetry traces are collected for this content item. Traces are collected only when both this field and the server setting Applications.AllowTraceCollection are true. Example: false.
owner_guid	string (uuid)	The unique identifier of the user who created this content item. Automatically assigned when the content is created. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
content_url	string	The URL associated with this content. Computed from the associated GUID for this content. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
dashboard_url	string	The URL within the Connect dashboard where this content can be configured. Computed from the GUID for this content. Example: https://posit-connect.company.com/connect/#/apps/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
vanity_url	string	The vanity URL associated with this content item. Included in responses when the vanity URL is set and include=vanity_url is provided. Example: https://posit-connect.company.com/my-content/.
app_role	string	The relationship of the accessing user to this content. A value of owner is returned for the content owner. editor indicates a collaborator. The viewer value is given to users who are permitted to view the content. A none role is returned for administrators who cannot view the content but are permitted to view its configuration. Computed at the time of the request. Example: owner.
bookmarked	boolean|null	Indicates whether the requesting user has bookmarked this content item. Included in responses when include=bookmarked is provided. Example: true.
schedules	[object]	Schedules associated with this content item. Included in responses when include=schedule is provided.
schedules[].type	string	The schedule type. Example: rrule.
schedules[].schedule	object	The recurrence rule in RFC5545 format.
schedules[].schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
schedules[].schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
schedules[].schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
schedules[].next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
schedules[].email	boolean	Whether email notifications are enabled for this schedule. Example: false.
schedules[].timezone	string	The timezone for this schedule. Example: America/New_York.
schedules[].start_time	string (date-time)|null	The start time of the schedule window.
schedules[].end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
schedules[].last_run	object	Information about the last scheduled run.
schedules[].last_run.job_key	string	The unique key of the job. Example: abc123xyz.
schedules[].last_run.status	string	The status of the last run. Example: success.
schedules[].last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
schedules[].last_run.queued_time	string (date-time)|null	The time the run was queued.
schedules[].last_run.start_time	string (date-time)	The time the run started.
schedules[].last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
schedules[].last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
schedules[].last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.
schedules[].variant	object	Variant information embedded in a schedule.
schedules[].variant.key	string	The variant key. Example: default.
schedules[].variant.name	string	The variant name. Example: Default Variant.
schedules[].variant.is_default	boolean	Whether this is the default variant. Example: true.
id	string	The internal numeric identifier of this content item. Example: 314.
tags	[object]	Tags associated with this content item. Included in responses when include=tags is provided. Returns an empty array when content has no tags.
tags[].id	string	The identifier for the tag. Example: 101.
tags[].name	string	The name of the tag. Example: financial-statements.
tags[].parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
tags[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
tags[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.
owner	object	Basic details about the owner of this content item. Included in responses when include=owner is provided.
owner.guid	string (uuid)	The owner’s unique identifier. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
owner.username	string|null	The owner’s username. Example: jondoe.
owner.first_name	string|null	The owner’s first name. Example: Jon.
owner.last_name	string|null	The owner’s last name. Example: Doe.
public_content_status	string|null	Validation status of public interactive content. When validation is required by licensing, this will be one of “ok”, “warning”, or “restricted”. If licensing does not require validation, it will be “unrestricted”; if licensing does not allow public interactive content, it will be “unlicensed”. If the app has not been made public, but public content is permitted, it will be “none”. Example: unrestricted.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create content item

POST /v1/content

Create a new content item.

Request body

The content fields that can be specified when creating a content item.

Name	Type	Description
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
access_type	string	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. Enum: all, logged_in, acl. Example: acl.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Example: rstudio-connect.
run_as_current_user	boolean|null	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Example: false.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in CPU Units, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in CPU Units. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs allocated to run this content. When null, the default Scheduler.AMDGPULimit is used. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs allocated to run this content. When null, the default Scheduler.NvidiaGPULimit is used. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account used to run this content. Example: rstudio-connect-content.
default_image_name	string|null	The default container image used when none is defined by the bundle’s manifest. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment used when none is defined by the bundle’s manifest. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics are collected for this content item. When null, inherits the server-wide default. Example: true.
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, inherits the server-wide default from Applications.NotifyOnShare. Example: true.
trace_collection_enabled	boolean|null	Controls whether per-job OpenTelemetry traces are collected for this content item. When null, inherits the server-wide default. Example: false.

Responses

200

200: Successful response.

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.

Name guid	Type string (uuid)	Description The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
access_type	string	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.
locked	boolean	Whether or not the content is locked. Example: false.
locked_message	string	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.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. If the process tries to use more memory than allowed, it will be terminated. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration. If the process tries to use more CPU than allowed, it will be throttled. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.AMDGPULimit is used. This setting can not exceed Scheduler.MaxAMDGPULimit. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.NvidiaGPULimit is used. This setting can not exceed Scheduler.MaxNvidiaGPULimit. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account that is used to run a particular piece of content. It must adhere to valid Kubernetes service account naming rules. Connect must be configured to run with Launcher.Enabled = true, Launcher.Kubernetes = true and Launcher.KubernetesContentServiceAccountSelection = true for this value to be applied. It will have precedence over the Launcher.KubernetesDefaultServiceAccount that may be set in the configuration for Connect. If this value is defined and Connect is configured with Launcher.KubernetesContentServiceAccountSelection = false an error will be returned. Only administrators and publishers can view this value. Only administrators can set or change this value. Example: rstudio-connect-content.
default_image_name	string|null	The default image that will be used when none is defined by the bundle’s manifest. A specific image may be selected by setting the environment.image field in the manifest. If no image is selected by the manifest file, then the default_image_name is used. If a target image is not defined by the manifest, and no default_image_name is configured, then Connect will select an image from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment that will be used when none is defined by the bundle’s manifest. A specific execution environment may be selected by setting the environment.identifier field in the manifest. If no execution environment is selected by the manifest file, then default_environment_guid is used to select the execution environment. If a target execution environment is not defined by the manifest, and no default_environment_guid is configured, then Connect will select an execution environment from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this content was created. Example: 2006-01-02T15:04:05-07:00.
last_deployed_time	string (date-time)	The timestamp (RFC3339) indicating when this content last had a successful bundle deployment performed. Example: 2006-01-02T15:04:05-07:00.
bundle_id	string|null	The identifier for the active deployment bundle. Automatically assigned upon the successful deployment of that bundle. Example: 101.
app_mode	string	The runtime model for this content. Has a value of unknown before data is deployed to this item. Automatically assigned upon the first successful bundle deployment. Valid values are: api - R code defining a Plumber API. jupyter-static - A Jupyter Notebook. jupyter-voila A Voila interactive dashboard. python-api - Python code defining a WSGI API (such as Flask) python-bokeh - Python code defining a Bokeh application. python-panel - Python code defining a Panel application. python-dash - Python code defining a Dash application. python-fastapi - Python code defining an ASGI API (such as FastAPI) python-gradio - Python code defining a Gradio application. python-shiny - Python code defining a Shiny application. python-streamlit - Python code defining a Streamlit application. quarto-shiny - A Quarto document with a Shiny runtime. quarto-static - A Quarto document or site. rmd-shiny - An R Markdown document with a Shiny runtime. rmd-static - An R Markdown document or site. shiny - R code defining a Shiny application. static - Content deployed without source; often HTML and plots. tensorflow-saved-model - A TensorFlow Model API. unknown - No known runtime model. Example: shiny.
content_category	string	Describes the specialization of the content runtime model. | Automatically assigned upon the first successful bundle deployment. | | The content_category field refines the type of content specified by | app_mode. It is empty by default. The rsconnect R package may assign | a value when analyzing your content and building its manifest and | bundle. Plots (images created in the RStudio IDE and presented in the | “Plots” pane) have an app_mode of static and receive a | content_category of plot to distinguish them from other HTML | documents. Pinned static data sets have an app_mode of static and a | content_category of pin. Multi-document R Markdown sites have an | app_mode of rmd-static and a content_category of site. | API content types (such as FastAPI, Flask, or Plumber) that serve as | MCP servers have a content_category of mcp. The mcp category is | auto-detected on first deploy but can also be set or cleared via | PATCH /v1/content/{guid}. | | Example: site. |
parameterized	boolean	True when R Markdown rendered content allows parameter configuration. Automatically assigned upon the first successful bundle deployment. Applies only to content with an app_mode of rmd-static. Example: false.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have either a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The of R interpreter associated with this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.5.1.
py_version	string|null	The version of Python associated with this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.8.2.
quarto_version	string|null	The version of Quarto associated with this content. A null represents that Quarto is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 0.2.22.
node_version	string|null	The version of Node.js associated with this content. A null represents that Node.js is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 22.11.0.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Only administrators can change this value. If Applications.RunAsEnabled = false, this value will be ignored when executing content. Example: rstudio-connect.
run_as_current_user	boolean	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Connect must be configured to use PAM authentication with the server settings Applications.RunAsCurrentUser = true and PAM.ForwardPassword = true. This setting has no effect for other authentication types. This setting only applies to application content types (Shiny, Dash, Streamlit, Bokeh, and Panel). Only administrators can change this value. Example: false.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics (CPU, memory, connections) | are collected for this content item. | | When null, the content item inherits the server-wide default from | Applications.MetricsCollectionEnabled. Explicit true or false | values override the server default. | | Metrics can be retrieved via the | GET /v1/content/{guid}/jobs/{key}/metrics endpoint. | Example: true. |
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, the content item inherits the server-wide default from Applications.NotifyOnShare. Explicit true or false values override the server default. Example: true.
trace_collection_enabled	boolean	Whether per-job OpenTelemetry traces are collected for this content item. Traces are collected only when both this field and the server setting Applications.AllowTraceCollection are true. Example: false.
owner_guid	string (uuid)	The unique identifier of the user who created this content item. Automatically assigned when the content is created. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
content_url	string	The URL associated with this content. Computed from the associated GUID for this content. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
dashboard_url	string	The URL within the Connect dashboard where this content can be configured. Computed from the GUID for this content. Example: https://posit-connect.company.com/connect/#/apps/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
vanity_url	string	The vanity URL associated with this content item. Included in responses when the vanity URL is set and include=vanity_url is provided. Example: https://posit-connect.company.com/my-content/.
app_role	string	The relationship of the accessing user to this content. A value of owner is returned for the content owner. editor indicates a collaborator. The viewer value is given to users who are permitted to view the content. A none role is returned for administrators who cannot view the content but are permitted to view its configuration. Computed at the time of the request. Example: owner.
bookmarked	boolean|null	Indicates whether the requesting user has bookmarked this content item. Included in responses when include=bookmarked is provided. Example: true.
schedules	[object]	Schedules associated with this content item. Included in responses when include=schedule is provided.
schedules[].type	string	The schedule type. Example: rrule.
schedules[].schedule	object	The recurrence rule in RFC5545 format.
schedules[].schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
schedules[].schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
schedules[].schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
schedules[].next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
schedules[].email	boolean	Whether email notifications are enabled for this schedule. Example: false.
schedules[].timezone	string	The timezone for this schedule. Example: America/New_York.
schedules[].start_time	string (date-time)|null	The start time of the schedule window.
schedules[].end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
schedules[].last_run	object	Information about the last scheduled run.
schedules[].last_run.job_key	string	The unique key of the job. Example: abc123xyz.
schedules[].last_run.status	string	The status of the last run. Example: success.
schedules[].last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
schedules[].last_run.queued_time	string (date-time)|null	The time the run was queued.
schedules[].last_run.start_time	string (date-time)	The time the run started.
schedules[].last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
schedules[].last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
schedules[].last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.
schedules[].variant	object	Variant information embedded in a schedule.
schedules[].variant.key	string	The variant key. Example: default.
schedules[].variant.name	string	The variant name. Example: Default Variant.
schedules[].variant.is_default	boolean	Whether this is the default variant. Example: true.
id	string	The internal numeric identifier of this content item. Example: 314.
tags	[object]	Tags associated with this content item. Included in responses when include=tags is provided. Returns an empty array when content has no tags.
tags[].id	string	The identifier for the tag. Example: 101.
tags[].name	string	The name of the tag. Example: financial-statements.
tags[].parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
tags[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
tags[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.
owner	object	Basic details about the owner of this content item. Included in responses when include=owner is provided.
owner.guid	string (uuid)	The owner’s unique identifier. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
owner.username	string|null	The owner’s username. Example: jondoe.
owner.first_name	string|null	The owner’s first name. Example: Jon.
owner.last_name	string|null	The owner’s last name. Example: Doe.
public_content_status	string|null	Validation status of public interactive content. When validation is required by licensing, this will be one of “ok”, “warning”, or “restricted”. If licensing does not require validation, it will be “unrestricted”; if licensing does not allow public interactive content, it will be “unlicensed”. If the app has not been made public, but public content is permitted, it will be “none”. Example: unrestricted.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get content details

GET /v1/content/{guid}

Get detailed information about a specific content item.

Unauthenticated clients are rejected regardless of the content access type.

Authorized, non-administrator clients without viewership rights to this content are rejected.

Authorized, administrator clients without viewership rights are permitted to obtain information about this content. The computed app_role for these users will be none, representing that these users cannot view the content itself.

Authorized clients with viewership (or collaborator) rights are permitted to obtain information about this content. The computed app_role for these users will reflect the level of access.

Information about the target environment is populated for users with “publisher” and “administrator” role; it is suppressed for viewers.

Parameters

Path parameters

Name	Type	Description
guid	string (uuid)	Required.

Query parameters

Name	Type	Description
include	string	Comma-separated set of values indicating additional details to include in the response. tags: Populates a tags field for each returned content item containing the tags associated with this content item. owner: Populates an owner field for each returned content item with basic details about the content owner. vanity_url: Populates the vanity_url field for each returned content item if the content has an associated custom vanity URL. bookmarked: Populates a bookmarked field for each returned content item indicating whether the requesting user has bookmarked the content. schedule: Populates a schedules field for each returned content item with the list of schedules associated with the content, including variant details and last run information.

Responses

200

200: Successful response.

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.

Name guid	Type string (uuid)	Description The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
access_type	string	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.
locked	boolean	Whether or not the content is locked. Example: false.
locked_message	string	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.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. If the process tries to use more memory than allowed, it will be terminated. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration. If the process tries to use more CPU than allowed, it will be throttled. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.AMDGPULimit is used. This setting can not exceed Scheduler.MaxAMDGPULimit. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.NvidiaGPULimit is used. This setting can not exceed Scheduler.MaxNvidiaGPULimit. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account that is used to run a particular piece of content. It must adhere to valid Kubernetes service account naming rules. Connect must be configured to run with Launcher.Enabled = true, Launcher.Kubernetes = true and Launcher.KubernetesContentServiceAccountSelection = true for this value to be applied. It will have precedence over the Launcher.KubernetesDefaultServiceAccount that may be set in the configuration for Connect. If this value is defined and Connect is configured with Launcher.KubernetesContentServiceAccountSelection = false an error will be returned. Only administrators and publishers can view this value. Only administrators can set or change this value. Example: rstudio-connect-content.
default_image_name	string|null	The default image that will be used when none is defined by the bundle’s manifest. A specific image may be selected by setting the environment.image field in the manifest. If no image is selected by the manifest file, then the default_image_name is used. If a target image is not defined by the manifest, and no default_image_name is configured, then Connect will select an image from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment that will be used when none is defined by the bundle’s manifest. A specific execution environment may be selected by setting the environment.identifier field in the manifest. If no execution environment is selected by the manifest file, then default_environment_guid is used to select the execution environment. If a target execution environment is not defined by the manifest, and no default_environment_guid is configured, then Connect will select an execution environment from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this content was created. Example: 2006-01-02T15:04:05-07:00.
last_deployed_time	string (date-time)	The timestamp (RFC3339) indicating when this content last had a successful bundle deployment performed. Example: 2006-01-02T15:04:05-07:00.
bundle_id	string|null	The identifier for the active deployment bundle. Automatically assigned upon the successful deployment of that bundle. Example: 101.
app_mode	string	The runtime model for this content. Has a value of unknown before data is deployed to this item. Automatically assigned upon the first successful bundle deployment. Valid values are: api - R code defining a Plumber API. jupyter-static - A Jupyter Notebook. jupyter-voila A Voila interactive dashboard. python-api - Python code defining a WSGI API (such as Flask) python-bokeh - Python code defining a Bokeh application. python-panel - Python code defining a Panel application. python-dash - Python code defining a Dash application. python-fastapi - Python code defining an ASGI API (such as FastAPI) python-gradio - Python code defining a Gradio application. python-shiny - Python code defining a Shiny application. python-streamlit - Python code defining a Streamlit application. quarto-shiny - A Quarto document with a Shiny runtime. quarto-static - A Quarto document or site. rmd-shiny - An R Markdown document with a Shiny runtime. rmd-static - An R Markdown document or site. shiny - R code defining a Shiny application. static - Content deployed without source; often HTML and plots. tensorflow-saved-model - A TensorFlow Model API. unknown - No known runtime model. Example: shiny.
content_category	string	Describes the specialization of the content runtime model. | Automatically assigned upon the first successful bundle deployment. | | The content_category field refines the type of content specified by | app_mode. It is empty by default. The rsconnect R package may assign | a value when analyzing your content and building its manifest and | bundle. Plots (images created in the RStudio IDE and presented in the | “Plots” pane) have an app_mode of static and receive a | content_category of plot to distinguish them from other HTML | documents. Pinned static data sets have an app_mode of static and a | content_category of pin. Multi-document R Markdown sites have an | app_mode of rmd-static and a content_category of site. | API content types (such as FastAPI, Flask, or Plumber) that serve as | MCP servers have a content_category of mcp. The mcp category is | auto-detected on first deploy but can also be set or cleared via | PATCH /v1/content/{guid}. | | Example: site. |
parameterized	boolean	True when R Markdown rendered content allows parameter configuration. Automatically assigned upon the first successful bundle deployment. Applies only to content with an app_mode of rmd-static. Example: false.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have either a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The of R interpreter associated with this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.5.1.
py_version	string|null	The version of Python associated with this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.8.2.
quarto_version	string|null	The version of Quarto associated with this content. A null represents that Quarto is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 0.2.22.
node_version	string|null	The version of Node.js associated with this content. A null represents that Node.js is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 22.11.0.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Only administrators can change this value. If Applications.RunAsEnabled = false, this value will be ignored when executing content. Example: rstudio-connect.
run_as_current_user	boolean	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Connect must be configured to use PAM authentication with the server settings Applications.RunAsCurrentUser = true and PAM.ForwardPassword = true. This setting has no effect for other authentication types. This setting only applies to application content types (Shiny, Dash, Streamlit, Bokeh, and Panel). Only administrators can change this value. Example: false.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics (CPU, memory, connections) | are collected for this content item. | | When null, the content item inherits the server-wide default from | Applications.MetricsCollectionEnabled. Explicit true or false | values override the server default. | | Metrics can be retrieved via the | GET /v1/content/{guid}/jobs/{key}/metrics endpoint. | Example: true. |
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, the content item inherits the server-wide default from Applications.NotifyOnShare. Explicit true or false values override the server default. Example: true.
trace_collection_enabled	boolean	Whether per-job OpenTelemetry traces are collected for this content item. Traces are collected only when both this field and the server setting Applications.AllowTraceCollection are true. Example: false.
owner_guid	string (uuid)	The unique identifier of the user who created this content item. Automatically assigned when the content is created. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
content_url	string	The URL associated with this content. Computed from the associated GUID for this content. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
dashboard_url	string	The URL within the Connect dashboard where this content can be configured. Computed from the GUID for this content. Example: https://posit-connect.company.com/connect/#/apps/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
vanity_url	string	The vanity URL associated with this content item. Included in responses when the vanity URL is set and include=vanity_url is provided. Example: https://posit-connect.company.com/my-content/.
app_role	string	The relationship of the accessing user to this content. A value of owner is returned for the content owner. editor indicates a collaborator. The viewer value is given to users who are permitted to view the content. A none role is returned for administrators who cannot view the content but are permitted to view its configuration. Computed at the time of the request. Example: owner.
bookmarked	boolean|null	Indicates whether the requesting user has bookmarked this content item. Included in responses when include=bookmarked is provided. Example: true.
schedules	[object]	Schedules associated with this content item. Included in responses when include=schedule is provided.
schedules[].type	string	The schedule type. Example: rrule.
schedules[].schedule	object	The recurrence rule in RFC5545 format.
schedules[].schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
schedules[].schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
schedules[].schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
schedules[].next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
schedules[].email	boolean	Whether email notifications are enabled for this schedule. Example: false.
schedules[].timezone	string	The timezone for this schedule. Example: America/New_York.
schedules[].start_time	string (date-time)|null	The start time of the schedule window.
schedules[].end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
schedules[].last_run	object	Information about the last scheduled run.
schedules[].last_run.job_key	string	The unique key of the job. Example: abc123xyz.
schedules[].last_run.status	string	The status of the last run. Example: success.
schedules[].last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
schedules[].last_run.queued_time	string (date-time)|null	The time the run was queued.
schedules[].last_run.start_time	string (date-time)	The time the run started.
schedules[].last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
schedules[].last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
schedules[].last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.
schedules[].variant	object	Variant information embedded in a schedule.
schedules[].variant.key	string	The variant key. Example: default.
schedules[].variant.name	string	The variant name. Example: Default Variant.
schedules[].variant.is_default	boolean	Whether this is the default variant. Example: true.
id	string	The internal numeric identifier of this content item. Example: 314.
tags	[object]	Tags associated with this content item. Included in responses when include=tags is provided. Returns an empty array when content has no tags.
tags[].id	string	The identifier for the tag. Example: 101.
tags[].name	string	The name of the tag. Example: financial-statements.
tags[].parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
tags[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
tags[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.
owner	object	Basic details about the owner of this content item. Included in responses when include=owner is provided.
owner.guid	string (uuid)	The owner’s unique identifier. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
owner.username	string|null	The owner’s username. Example: jondoe.
owner.first_name	string|null	The owner’s first name. Example: Jon.
owner.last_name	string|null	The owner’s last name. Example: Doe.
public_content_status	string|null	Validation status of public interactive content. When validation is required by licensing, this will be one of “ok”, “warning”, or “restricted”. If licensing does not require validation, it will be “unrestricted”; if licensing does not allow public interactive content, it will be “unlicensed”. If the app has not been made public, but public content is permitted, it will be “none”. Example: unrestricted.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update content

PATCH /v1/content/{guid}

Update fields for a specific content item.

Authenticated access from a user having either “publisher” or “administrator” role is allowed. All other clients are rejected.

Authorized clients with collaborator or administrator rights are permitted to modify content item fields.

Administrators can reassign content ownership by updating the owner_guid field. The new owner must have publisher or administrator rights.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The content fields that can be specified when updating a content item.

Name	Type	Description
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
owner_guid	string (uuid)|null	The unique identifier of the user who owns this content item. Can only be changed by an administrator. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
access_type	string	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. Enum: all, logged_in, acl. Example: acl.
locked	boolean|null	Whether or not the content is locked. Example: false.
locked_message	string|null	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.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Example: rstudio-connect.
run_as_current_user	boolean|null	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Example: false.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in CPU Units, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in CPU Units. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs allocated to run this content. When null, the default Scheduler.AMDGPULimit is used. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs allocated to run this content. When null, the default Scheduler.NvidiaGPULimit is used. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account used to run this content. Example: rstudio-connect-content.
default_image_name	string|null	The default container image used when none is defined by the bundle’s manifest. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment used when none is defined by the bundle’s manifest. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics are collected for this content item. When null, inherits the server-wide default. Example: true.
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, inherits the server-wide default from Applications.NotifyOnShare. Example: true.
trace_collection_enabled	boolean|null	Controls whether per-job OpenTelemetry traces are collected for this content item. When null, inherits the server-wide default. Example: false.
content_category	string|null	The content_category field refines the type of content specified by app_mode. For example, the MCP content category indicates content that serves as an MCP server. Allowed values are "" (empty string to clear) or "mcp". Example: mcp.

Responses

200

200: Successful response.

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.

Name guid	Type string (uuid)	Description The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
access_type	string	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.
locked	boolean	Whether or not the content is locked. Example: false.
locked_message	string	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.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. If the process tries to use more memory than allowed, it will be terminated. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration. If the process tries to use more CPU than allowed, it will be throttled. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.AMDGPULimit is used. This setting can not exceed Scheduler.MaxAMDGPULimit. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.NvidiaGPULimit is used. This setting can not exceed Scheduler.MaxNvidiaGPULimit. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account that is used to run a particular piece of content. It must adhere to valid Kubernetes service account naming rules. Connect must be configured to run with Launcher.Enabled = true, Launcher.Kubernetes = true and Launcher.KubernetesContentServiceAccountSelection = true for this value to be applied. It will have precedence over the Launcher.KubernetesDefaultServiceAccount that may be set in the configuration for Connect. If this value is defined and Connect is configured with Launcher.KubernetesContentServiceAccountSelection = false an error will be returned. Only administrators and publishers can view this value. Only administrators can set or change this value. Example: rstudio-connect-content.
default_image_name	string|null	The default image that will be used when none is defined by the bundle’s manifest. A specific image may be selected by setting the environment.image field in the manifest. If no image is selected by the manifest file, then the default_image_name is used. If a target image is not defined by the manifest, and no default_image_name is configured, then Connect will select an image from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment that will be used when none is defined by the bundle’s manifest. A specific execution environment may be selected by setting the environment.identifier field in the manifest. If no execution environment is selected by the manifest file, then default_environment_guid is used to select the execution environment. If a target execution environment is not defined by the manifest, and no default_environment_guid is configured, then Connect will select an execution environment from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this content was created. Example: 2006-01-02T15:04:05-07:00.
last_deployed_time	string (date-time)	The timestamp (RFC3339) indicating when this content last had a successful bundle deployment performed. Example: 2006-01-02T15:04:05-07:00.
bundle_id	string|null	The identifier for the active deployment bundle. Automatically assigned upon the successful deployment of that bundle. Example: 101.
app_mode	string	The runtime model for this content. Has a value of unknown before data is deployed to this item. Automatically assigned upon the first successful bundle deployment. Valid values are: api - R code defining a Plumber API. jupyter-static - A Jupyter Notebook. jupyter-voila A Voila interactive dashboard. python-api - Python code defining a WSGI API (such as Flask) python-bokeh - Python code defining a Bokeh application. python-panel - Python code defining a Panel application. python-dash - Python code defining a Dash application. python-fastapi - Python code defining an ASGI API (such as FastAPI) python-gradio - Python code defining a Gradio application. python-shiny - Python code defining a Shiny application. python-streamlit - Python code defining a Streamlit application. quarto-shiny - A Quarto document with a Shiny runtime. quarto-static - A Quarto document or site. rmd-shiny - An R Markdown document with a Shiny runtime. rmd-static - An R Markdown document or site. shiny - R code defining a Shiny application. static - Content deployed without source; often HTML and plots. tensorflow-saved-model - A TensorFlow Model API. unknown - No known runtime model. Example: shiny.
content_category	string	Describes the specialization of the content runtime model. | Automatically assigned upon the first successful bundle deployment. | | The content_category field refines the type of content specified by | app_mode. It is empty by default. The rsconnect R package may assign | a value when analyzing your content and building its manifest and | bundle. Plots (images created in the RStudio IDE and presented in the | “Plots” pane) have an app_mode of static and receive a | content_category of plot to distinguish them from other HTML | documents. Pinned static data sets have an app_mode of static and a | content_category of pin. Multi-document R Markdown sites have an | app_mode of rmd-static and a content_category of site. | API content types (such as FastAPI, Flask, or Plumber) that serve as | MCP servers have a content_category of mcp. The mcp category is | auto-detected on first deploy but can also be set or cleared via | PATCH /v1/content/{guid}. | | Example: site. |
parameterized	boolean	True when R Markdown rendered content allows parameter configuration. Automatically assigned upon the first successful bundle deployment. Applies only to content with an app_mode of rmd-static. Example: false.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have either a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The of R interpreter associated with this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.5.1.
py_version	string|null	The version of Python associated with this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.8.2.
quarto_version	string|null	The version of Quarto associated with this content. A null represents that Quarto is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 0.2.22.
node_version	string|null	The version of Node.js associated with this content. A null represents that Node.js is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 22.11.0.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Only administrators can change this value. If Applications.RunAsEnabled = false, this value will be ignored when executing content. Example: rstudio-connect.
run_as_current_user	boolean	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Connect must be configured to use PAM authentication with the server settings Applications.RunAsCurrentUser = true and PAM.ForwardPassword = true. This setting has no effect for other authentication types. This setting only applies to application content types (Shiny, Dash, Streamlit, Bokeh, and Panel). Only administrators can change this value. Example: false.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics (CPU, memory, connections) | are collected for this content item. | | When null, the content item inherits the server-wide default from | Applications.MetricsCollectionEnabled. Explicit true or false | values override the server default. | | Metrics can be retrieved via the | GET /v1/content/{guid}/jobs/{key}/metrics endpoint. | Example: true. |
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, the content item inherits the server-wide default from Applications.NotifyOnShare. Explicit true or false values override the server default. Example: true.
trace_collection_enabled	boolean	Whether per-job OpenTelemetry traces are collected for this content item. Traces are collected only when both this field and the server setting Applications.AllowTraceCollection are true. Example: false.
owner_guid	string (uuid)	The unique identifier of the user who created this content item. Automatically assigned when the content is created. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
content_url	string	The URL associated with this content. Computed from the associated GUID for this content. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
dashboard_url	string	The URL within the Connect dashboard where this content can be configured. Computed from the GUID for this content. Example: https://posit-connect.company.com/connect/#/apps/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
vanity_url	string	The vanity URL associated with this content item. Included in responses when the vanity URL is set and include=vanity_url is provided. Example: https://posit-connect.company.com/my-content/.
app_role	string	The relationship of the accessing user to this content. A value of owner is returned for the content owner. editor indicates a collaborator. The viewer value is given to users who are permitted to view the content. A none role is returned for administrators who cannot view the content but are permitted to view its configuration. Computed at the time of the request. Example: owner.
bookmarked	boolean|null	Indicates whether the requesting user has bookmarked this content item. Included in responses when include=bookmarked is provided. Example: true.
schedules	[object]	Schedules associated with this content item. Included in responses when include=schedule is provided.
schedules[].type	string	The schedule type. Example: rrule.
schedules[].schedule	object	The recurrence rule in RFC5545 format.
schedules[].schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
schedules[].schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
schedules[].schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
schedules[].next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
schedules[].email	boolean	Whether email notifications are enabled for this schedule. Example: false.
schedules[].timezone	string	The timezone for this schedule. Example: America/New_York.
schedules[].start_time	string (date-time)|null	The start time of the schedule window.
schedules[].end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
schedules[].last_run	object	Information about the last scheduled run.
schedules[].last_run.job_key	string	The unique key of the job. Example: abc123xyz.
schedules[].last_run.status	string	The status of the last run. Example: success.
schedules[].last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
schedules[].last_run.queued_time	string (date-time)|null	The time the run was queued.
schedules[].last_run.start_time	string (date-time)	The time the run started.
schedules[].last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
schedules[].last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
schedules[].last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.
schedules[].variant	object	Variant information embedded in a schedule.
schedules[].variant.key	string	The variant key. Example: default.
schedules[].variant.name	string	The variant name. Example: Default Variant.
schedules[].variant.is_default	boolean	Whether this is the default variant. Example: true.
id	string	The internal numeric identifier of this content item. Example: 314.
tags	[object]	Tags associated with this content item. Included in responses when include=tags is provided. Returns an empty array when content has no tags.
tags[].id	string	The identifier for the tag. Example: 101.
tags[].name	string	The name of the tag. Example: financial-statements.
tags[].parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
tags[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
tags[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.
owner	object	Basic details about the owner of this content item. Included in responses when include=owner is provided.
owner.guid	string (uuid)	The owner’s unique identifier. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
owner.username	string|null	The owner’s username. Example: jondoe.
owner.first_name	string|null	The owner’s first name. Example: Jon.
owner.last_name	string|null	The owner’s last name. Example: Doe.
public_content_status	string|null	Validation status of public interactive content. When validation is required by licensing, this will be one of “ok”, “warning”, or “restricted”. If licensing does not require validation, it will be “unrestricted”; if licensing does not allow public interactive content, it will be “unlicensed”. If the app has not been made public, but public content is permitted, it will be “none”. Example: unrestricted.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete content

DELETE /v1/content/{guid}

Delete a specific content item. On-disk data and database records are removed.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Triggers a Public Access Content Verification test

POST /v1/content/{guid}/access-test

Trigger a Public Access Content Verification test for this content item.

Checks if a content item is available and reachable on the public internet. If not, the result includes a message to help with troubleshooting. The verification process is identical to the test Connect performs automatically for all Public Access Content, but the API can provide more details about verification failures or immediately retest an item instead of waiting for the automatic verification to run.

See the Admin Guide and User Guide for more information about Public Access Content Verification.

To use this API, you must have a license with the Public Access entitlement, the content item must be interactive (e.g. Shiny applications, FastAPI APIs), and the content item must be configured with the “Anyone - no login required”/all access type.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

The results of the public access content verification test.

Name	Type	Description
guid	string (uuid)	The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
url	string	The URL that was used to test access to this content. Computed from the associated GUID for this content or the optional vanity URL. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
checked_at	string (date-time)	The timestamp (RFC3339) indicating when the access test was performed. Example: 2006-01-02T15:04:05-07:00.
accessible	boolean	Indicates whether or not the test was able to access the content item on the public internet. Example: false.
message	string	An optional informational message with extra details about the test result. See the Admin Guide for additional guidance about specific messages. Example: content is not publicly accessible.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Build deployment bundle

POST /v1/content/{guid}/build

Build (restore) a deployment bundle.

Build requests spawn an asynchronous task to make your previously uploaded data ready for rendering or running. Content will have its environment reconstructed, e.g. by using the packrat R package to install R package dependencies, but documents will not be re-rendered.

Building is intended to facilitate server changes or migrations that may require re-installing R packages or other dependencies.

By default, the built bundle becomes the active bundle for the content. You can prevent this by setting activate: false in the request body. This allows you to build a bundle without making it the active version.

The response from this endpoint includes a task identifier. Poll the GET /v1/tasks/{id} endpoint to track the progress of this task.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

Optionally identifies the target build bundle.

Name	Type	Description
bundle_id	string|null	The identifier of the bundle to build. If not provided, the most recently uploaded bundle is built.
activate	boolean|null	Whether the built bundle should be activated after building. Defaults to true.

Responses

200

200: Successful response.

Identifies the task that can be used to track the progress of a build operation.

Name	Type	Description
task_id	string	Identifier for the created build task. Example: M49MsuXt6XVzlRdL.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Deploy deployment bundle

POST /v1/content/{guid}/deploy

Deploy (activate) a deployment bundle.

Deployment requests spawn an asynchronous task to make your previously uploaded data available for serving. The workflow applied to the bundled files varies depending on the type of content.

Executable content has its environment reconstructed. This includes using the packrat R package to install R package dependencies.

Documents (R Markdown reports, Jupyter Notebooks, static Quarto content) are rendered and the result made available.

Interactive content (applications and APIs) are available to be launched on the next client visit.

The deployment workflow for static content (HTML, plots) is lighter-weight than for executable content. File time-stamps are updated to ensure that browsers do not cache previous results and instead see the newly promoted files.

By default, the deployed bundle becomes the active bundle for the content. You can prevent this by setting activate: false in the request body. This allows you to deploy a bundle without making it the active version.

The response from this endpoint includes a task identifier. Poll the GET /v1/tasks/{id} endpoint to track the progress of this task.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

Optionally identifies the target deployment bundle.

Name	Type	Description
bundle_id	string|null	The identifier of the bundle to deploy. If not provided, the most recently uploaded bundle is deployed.
activate	boolean|null	Whether the deployed bundle should be activated after deployment. Defaults to true.

Responses

202

202: Successful response.

Identifies the task that can be used to track the progress of a deployment operation.

Name	Type	Description
task_id	string	Identifier for the created deployment task. Example: M49MsuXt6XVzlRdL.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get environment variables

GET /v1/content/{guid}/environment

Get the names of the environment variables defined for this content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

List of environment variable names, without values.

Array of string

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Set all environment variables

PUT /v1/content/{guid}/environment

Set the environment for this content item. Any existing environment variables will be removed.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

List of environment variables with their values.

Array of objects:

Defines an environment variable and its value.

Name	Type	Description
name	string	Name of the environment variable. Example: DEBUG.
value	string|null	New value of the environment variable. A value of null will delete the environment variable. Example: 1.

Responses

200

200: Successful response.

List of environment variable names, without values.

Array of string

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update environment variables

PATCH /v1/content/{guid}/environment

Add, change, or delete environment variables for this content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

List of environment variables with their values.

Array of objects:

Defines an environment variable and its value.

Name	Type	Description
name	string	Name of the environment variable. Example: DEBUG.
value	string|null	New value of the environment variable. A value of null will delete the environment variable. Example: 1.

Responses

200

200: Successful response.

List of environment variable names, without values.

Array of string

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get Python lockfile

GET /v1/content/{guid}/lockfile

Get the Python lockfile (requirements.txt.lock) for a content item’s active bundle.

This endpoint returns the lockfile that describes the exact Python packages installed in Connect’s managed Python environment for this content. The file can be used to recreate the same Python environment elsewhere.

The content must have a managed Python environment (py_environment_management enabled). Returns an error if the content does not use Python or does not have environment management enabled.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List all OAuth integration associations for this content item

GET /v1/content/{guid}/oauth/integrations/associations

List all OAuth integration associations for this content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Represents an association between a content item and an OAuth integration.

Name	Type	Description
app_guid	string (uuid)	This field is deprecated and has been renamed to content_guid. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
content_guid	string (uuid)	The unique identifier of the content item. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
oauth_integration_guid	string (uuid)	The unique identifier of an existing OAuth integration. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
oauth_integration_name	string|null	A descriptive name that identifies the OAuth integration. Example: Databricks Integration.
oauth_integration_description	string|null	A brief text that describes the OAuth integration. Example: Integration with external system.
oauth_integration_template	string|null	The template used to configure this OAuth integration. Example: custom.
oauth_integration_auth_type	string|null	Indicates which OAuth flow is used by this integration. The “Viewer” authentication type corresponds to the Authorization Code flow. The “Service Account” authentication type corresponds to the Client Credentials flow. Example: Viewer.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this association was created. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Set all OAuth integration associations

PUT /v1/content/{guid}/oauth/integrations/associations

Replaces any existing associations for a piece of content with the given list.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

An OAuth integration GUID to associate with a content item.

Name	Type	Description
oauth_integration_guid	string (uuid)	The unique identifier of an existing OAuth integration. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get package dependencies

GET /v1/content/{guid}/packages

Get the names and versions of all R and Python packages installed for this content. Returned packages are sorted by language and then by package name.

If the content is not yet deployed, an HTTP 204 No Content response is returned. If the content environment is being rebuilt, package information from before the rebuild will be returned.

Note that a content item may include packages that are not explicitly requested in the manifest.json or requirements.txt file used during deployment. These include packages that are: - Installed as dependencies of the explicitly requested packages, - Installed by Connect in order to render or serve the content item, - Installed in the base Python installation and inherited by the content item, or - Listed under R.External in the Connect configuration file.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Lists the packages installed for a content item.

Array of objects:

A package dependency record.

Name	Type	Description
language	string	Language ecosystem the package belongs to
language_version	string	Version of R or Python used by the content Example: 3.12.4.
name	string	Package name Example: shiny.
version	string	Package version Example: 1.0.3.
hash	string|null	Package description hash for R packages Example: e4ac73dd20b2f6420742aac66e5d3e78.
bundle_id	string	Identifier for the bundle that depends on this package Example: 449.
app_id	string	This field is deprecated and has been renamed to content_id. Example: 145.
app_guid	string (uuid)	This field is deprecated and has been renamed to content_guid. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
content_id	string	Numeric identifier for the content that depends on this package Example: 145.
content_guid	string (uuid)	The unique identifier of the content item that depends on this package Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Render content

POST /v1/content/{guid}/render

Render a specific content item.

Render requests spawn an asynchronous task to re-render static reports (R Markdown documents, Jupyter Notebooks, or Quarto documents). The rendered output becomes the active rendering for the variant.

By default, the default variant is rendered. You can render a specific variant by providing its key in the request body.

Users with “editor” or higher role on the content can render any public variant, and private variants they own. Users with “viewer” role can only render ad-hoc variants when the Applications.ViewerOnDemandReports server setting is enabled.

The response from this endpoint includes a task identifier. Poll the GET /v1/tasks/{id} endpoint to track the progress of this task.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

Instructions for rendering a content item.

Name	Type	Description
variant_key	string|null	The key of the variant to render. If not specified, the default variant is rendered. Example: HidI2Kwq.

Responses

202

202: Successful response.

The result of requesting a content render, containing a task identifier.

Name	Type	Description
task_id	string	Identifier for the created render task. Example: M49MsuXt6XVzlRdL.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get Git repository

GET /v1/content/{guid}/repository

Get the Git repository location associated with this content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Git location associated with a content item.

Name	Type	Description
repository	string	URL for the repository. Example: https://github.com/rstudio/connect-examples.
branch	string	The tracked Git branch. Example: main.
directory	string	Directory containing the content. Example: stock-report.
polling	boolean	Indicates that the Git repository is regularly polled. Example: false.
last_error	string	The last error encountered when polling the Git repository, if one occurred. Example: The requested operation requires authentication..
last_known_commit	string	The last known commit in the Git repository. Example: a8906feae5c7675b934b7d22eb5fbd12ce51f1ba.
last_fetched_time	string (date-time)	The last time the Git repository was fetched. Example: 2026-04-14T12:00:00Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Set Git repository

PUT /v1/content/{guid}/repository

Associate a Git repository location with this content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

Git location associated with a content item.

Name	Type	Description
repository	string	URL for the repository. Example: https://github.com/rstudio/connect-examples.
branch	string	The tracked Git branch. Example: main.
directory	string	Directory containing the content. Example: stock-report.
polling	boolean	Indicates that the Git repository should be regularly polled. Example: false.

Responses

200

200: Successful response.

Git location associated with a content item.

Name	Type	Description
repository	string	URL for the repository. Example: https://github.com/rstudio/connect-examples.
branch	string	The tracked Git branch. Example: main.
directory	string	Directory containing the content. Example: stock-report.
polling	boolean	Indicates that the Git repository is regularly polled. Example: false.
last_error	string	The last error encountered when polling the Git repository, if one occurred. Example: The requested operation requires authentication..
last_known_commit	string	The last known commit in the Git repository. Example: a8906feae5c7675b934b7d22eb5fbd12ce51f1ba.
last_fetched_time	string (date-time)	The last time the Git repository was fetched. Example: 2026-04-14T12:00:00Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update Git repository

PATCH /v1/content/{guid}/repository

Update the Git repository location associated with this content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

Git location associated with a content item.

Name	Type	Description
repository	string	URL for the repository. Example: https://github.com/rstudio/connect-examples.
branch	string	The tracked Git branch. Example: main.
directory	string	Directory containing the content. Example: stock-report.
polling	boolean	Indicates that the Git repository should be regularly polled. Example: false.

Responses

200

200: Successful response.

Git location associated with a content item.

Name	Type	Description
repository	string	URL for the repository. Example: https://github.com/rstudio/connect-examples.
branch	string	The tracked Git branch. Example: main.
directory	string	Directory containing the content. Example: stock-report.
polling	boolean	Indicates that the Git repository is regularly polled. Example: false.
last_error	string	The last error encountered when polling the Git repository, if one occurred. Example: The requested operation requires authentication..
last_known_commit	string	The last known commit in the Git repository. Example: a8906feae5c7675b934b7d22eb5fbd12ce51f1ba.
last_fetched_time	string (date-time)	The last time the Git repository was fetched. Example: 2026-04-14T12:00:00Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Remove Git repository location

DELETE /v1/content/{guid}/repository

Remove the Git repository location associated with this content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Set a content thumbnail

PUT /v1/content/{guid}/thumbnail

Set a content thumbnail.

Associate a content item with an image that is used as its thumbnail in the Connect dashboard content listing and settings view.

Requesting a thumbnail

The thumbnail is requested by appending a __thumbnail__ path segment to the default content URL or a content vanity URL.

For example, the thumbnail for a content item having the GUID 25438b83-ea6d-4839-ae8e-53c52ac5f9ce and the vanity URL /daily-summary/ is served at the URLs:

• https://connect.company.com/content/25438b83-ea6d-4839-ae8e-53c52ac5f9ce/__thumbnail__
• https://connect.company.com/daily-summary/__thumbnail__

Thumbnail requests are subject to content access restrictions. An HTTP 204 No Content is served when there is no thumbnail. Thumbnails are not served for incomplete content.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

string (binary)

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete a content thumbnail

DELETE /v1/content/{guid}/thumbnail

Delete the thumbnail associated with a content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Search for content items

GET /v1/search/content

This endpoint searches for content items, using a search query format that allows for both search terms and filters. The search terms are used to find content items that have matching terms in the title, description, etc, while the filters are used to filter the search results by specific fields (such as owner or content type).

Authenticated access is required, and only content items visible to the requesting user are returned. If an Administrator role is used, then all content items are returned regardless of the visibility to the requesting user.

Search query

The search query is a string that includes both search terms and filters. Any text in the search query that is not a supported filter is treated as a search term, and those search terms are matched against any of: name, title, or description. Note that the search terms are case-insensitive, and all terms must be present in a content item for it to be included in the search results.

Filters

Filters are specified as colon-delimited key-value pairs, containing one or more values separated by commas. If any of the values within a filter contain a space or comma, you should use quotes around the value. Example:

myterm tag:tagwithoutspace,"tag with space"

For filters that expect a boolean value (like published:, locked:, and bookmarked:), you can use the shorthand is:<field> as an equivalent to <field>:true. Similarly, you can use not:<field> as an equivalent to <field>:false. Examples:

is:published

not:locked

is:bookmarked

Additionally, you can negate a filter or search term by prefixing it with a -. For example, -owner:@me will exclude content items owned by the requesting user.

The following filters are supported:

owner:<username>[,<additional-usernames>,...]: Only return content items that have the specified owner by username. If more than one username is provided, content items owned by ANY of the specified owners will be included. Note that usernames are not case sensitive.

type:<content-type>[,<additional-content-types>,...]: Only return content items that have the specified content type. If more than one type is provided, content items with ANY of the specified types will be included. See app_mode for a list of supported types and their description.

tag:<tag-name>[,<additional-tag-names>,...]: Only return content items that have been tagged with the specified tag name. If more than one tag name is provided, content items with any of the specified tag names are included. Additionally, since tags are hierarchical, they do not necessarily have unique names. For example, you may have one docs tag that is nested under a finance tag, and a separate docs tag that is nested under an engineering tag. If you specify tag:docs, it will match content items with either of those docs tags. If you want a specific tag, you can specify the path to the tag, delimited by /. In this case, tag:finance/docs would only match the docs tag that is nested directly under the finance tag.

published:<true|false> - Only return content items that have been published, which means that a bundle has been uploaded for the content item.

locked:<true|false> - Only return content items that have been locked.

bookmarked:<true|false> - Only return content items that have been bookmarked by the requesting user.

scheduled:<true|false> - Only return content items that have been scheduled to run on a recurring basis.

python:<version> - Only return content items that use a specific Python version in their runtime environment. The version can be specified as 3, 3.11, or 3.11.5. You can find content items that use any version of Python by specifying is:python.

r:<version> - Only return content items that use a specific R version in their runtime environment. The version can be specified as 4, 4.3, or 4.3.1. You can find content items that use any version of R by specifying is:r.

package:<name>[version] - Only return content items that have a specific package in their runtime environment. If a version specification is provided, only return content items that have a matching version for the package. Examples:

• flask: Return items that include the flask package.
• flask==2.3.4: Return items that include flask version 2.3.4. Versions ending in .0 are equivalent to versions without the .0.
• flask==2.3.*: Return items that include any flask version starting with 2.3.
• flask>=2.3: Return items that include flask version 2.3 or newer.
• Similarly, you can use <=, <, >, and !=. You can combine criteria with commas, such as "flask>=2.3,<3"; those must be enclosed in double-quotes. Alternatively, you can use the package filter multiple times: package:flask>=2.3 package:flask<3.
• flask~=2.3.4: Return items that include a flask version compatible with 2.3.4; that is, a 2.3.x version that is >=2.3.4.
• flask===2.3: Return items that include a flask version that exactly matches 2.3. Version 2.3.0 would not match this filter.

Note that a content item may include packages that are not explicitly requested in the manifest.json or requirements.txt file used during deployment. These include packages that are:

• Installed as dependencies of the explicitly requested packages,
• Installed by Connect in order to render or serve the content item,
• Installed in the base Python installation and inherited by the content item, or
• Listed under R.External in the Connect configuration file.

image:<image_name> - Only return content items that use a specific image in their execution environment. This filter performs partial string matching on the image name in either the image_name or default_image_name content fields.

Validation warnings

When a filter value is invalid (for example, published:bogus instead of published:true), the invalid filter is ignored and the response includes a warnings array with messages explaining which filters were not applied and why. Results are returned as if the invalid filter was not specified.

Pagination

This endpoint uses offset pagination. Requests can include query-string parameters for page_number and page_size to fetch different pages of results.

Parameters

Name	Type	Description
q	string
include	string	Comma-separated set of values indicating additional details to include in the response. tags: Populates a tags field for each returned content item containing the tags associated with this content item. owner: Populates an owner field for each returned content item with basic details about the content owner. vanity_url: Populates the vanity_url field for each returned content item if the content has an associated custom vanity URL. bookmarked: Populates a bookmarked field for each returned content item indicating whether the requesting user has bookmarked the content. schedule: Populates a schedules field for each returned content item with the list of schedules associated with the content, including variant details and last run information.
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
sort	string	The field to sort by.
order	string	The sort order: asc or desc.

Responses

200

200: Successful response.

Search results containing content items and pagination metadata.

Name current_page	Type integer	Description The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The list of content items, paginated
results[].guid	string (uuid)	The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
results[].name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
results[].title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
results[].description	string	A rich description of this content. Example: This report calculates per-team statistics ....
results[].access_type	string	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.
results[].locked	boolean	Whether or not the content is locked. Example: false.
results[].locked_message	string	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.
results[].connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
results[].read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
results[].init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
results[].idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
results[].max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
results[].min_processes	integer|null	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.
results[].max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
results[].load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
results[].memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
results[].memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. If the process tries to use more memory than allowed, it will be terminated. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
results[].cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.CPURequest is used. Example: 1.
results[].cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration. If the process tries to use more CPU than allowed, it will be throttled. When null, the default Scheduler.CPULimit is used. Example: 1.5.
results[].amd_gpu_limit	integer|null	The number of AMD GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.AMDGPULimit is used. This setting can not exceed Scheduler.MaxAMDGPULimit. Example: 1.
results[].nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.NvidiaGPULimit is used. This setting can not exceed Scheduler.MaxNvidiaGPULimit. Example: 1.
results[].service_account_name	string|null	The name of the Kubernetes service account that is used to run a particular piece of content. It must adhere to valid Kubernetes service account naming rules. Connect must be configured to run with Launcher.Enabled = true, Launcher.Kubernetes = true and Launcher.KubernetesContentServiceAccountSelection = true for this value to be applied. It will have precedence over the Launcher.KubernetesDefaultServiceAccount that may be set in the configuration for Connect. If this value is defined and Connect is configured with Launcher.KubernetesContentServiceAccountSelection = false an error will be returned. Only administrators and publishers can view this value. Only administrators can set or change this value. Example: rstudio-connect-content.
results[].default_image_name	string|null	The default image that will be used when none is defined by the bundle’s manifest. A specific image may be selected by setting the environment.image field in the manifest. If no image is selected by the manifest file, then the default_image_name is used. If a target image is not defined by the manifest, and no default_image_name is configured, then Connect will select an image from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
results[].default_environment_guid	string (uuid)|null	The default execution environment that will be used when none is defined by the bundle’s manifest. A specific execution environment may be selected by setting the environment.identifier field in the manifest. If no execution environment is selected by the manifest file, then default_environment_guid is used to select the execution environment. If a target execution environment is not defined by the manifest, and no default_environment_guid is configured, then Connect will select an execution environment from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
results[].created_time	string (date-time)	The timestamp (RFC3339) indicating when this content was created. Example: 2006-01-02T15:04:05-07:00.
results[].last_deployed_time	string (date-time)	The timestamp (RFC3339) indicating when this content last had a successful bundle deployment performed. Example: 2006-01-02T15:04:05-07:00.
results[].bundle_id	string|null	The identifier for the active deployment bundle. Automatically assigned upon the successful deployment of that bundle. Example: 101.
results[].app_mode	string	The runtime model for this content. Has a value of unknown before data is deployed to this item. Automatically assigned upon the first successful bundle deployment. Valid values are: api - R code defining a Plumber API. jupyter-static - A Jupyter Notebook. jupyter-voila A Voila interactive dashboard. python-api - Python code defining a WSGI API (such as Flask) python-bokeh - Python code defining a Bokeh application. python-panel - Python code defining a Panel application. python-dash - Python code defining a Dash application. python-fastapi - Python code defining an ASGI API (such as FastAPI) python-gradio - Python code defining a Gradio application. python-shiny - Python code defining a Shiny application. python-streamlit - Python code defining a Streamlit application. quarto-shiny - A Quarto document with a Shiny runtime. quarto-static - A Quarto document or site. rmd-shiny - An R Markdown document with a Shiny runtime. rmd-static - An R Markdown document or site. shiny - R code defining a Shiny application. static - Content deployed without source; often HTML and plots. tensorflow-saved-model - A TensorFlow Model API. unknown - No known runtime model. Example: shiny.
results[].content_category	string	Describes the specialization of the content runtime model. | Automatically assigned upon the first successful bundle deployment. | | The content_category field refines the type of content specified by | app_mode. It is empty by default. The rsconnect R package may assign | a value when analyzing your content and building its manifest and | bundle. Plots (images created in the RStudio IDE and presented in the | “Plots” pane) have an app_mode of static and receive a | content_category of plot to distinguish them from other HTML | documents. Pinned static data sets have an app_mode of static and a | content_category of pin. Multi-document R Markdown sites have an | app_mode of rmd-static and a content_category of site. | API content types (such as FastAPI, Flask, or Plumber) that serve as | MCP servers have a content_category of mcp. The mcp category is | auto-detected on first deploy but can also be set or cleared via | PATCH /v1/content/{guid}. | | Example: site. |
results[].parameterized	boolean	True when R Markdown rendered content allows parameter configuration. Automatically assigned upon the first successful bundle deployment. Applies only to content with an app_mode of rmd-static. Example: false.
results[].environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have either a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
results[].cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
results[].image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
results[].r_version	string|null	The of R interpreter associated with this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.5.1.
results[].py_version	string|null	The version of Python associated with this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.8.2.
results[].quarto_version	string|null	The version of Quarto associated with this content. A null represents that Quarto is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 0.2.22.
results[].node_version	string|null	The version of Node.js associated with this content. A null represents that Node.js is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 22.11.0.
results[].r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
results[].default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
results[].py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
results[].default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
results[].run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Only administrators can change this value. If Applications.RunAsEnabled = false, this value will be ignored when executing content. Example: rstudio-connect.
results[].run_as_current_user	boolean	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Connect must be configured to use PAM authentication with the server settings Applications.RunAsCurrentUser = true and PAM.ForwardPassword = true. This setting has no effect for other authentication types. This setting only applies to application content types (Shiny, Dash, Streamlit, Bokeh, and Panel). Only administrators can change this value. Example: false.
results[].metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics (CPU, memory, connections) | are collected for this content item. | | When null, the content item inherits the server-wide default from | Applications.MetricsCollectionEnabled. Explicit true or false | values override the server default. | | Metrics can be retrieved via the | GET /v1/content/{guid}/jobs/{key}/metrics endpoint. | Example: true. |
results[].notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, the content item inherits the server-wide default from Applications.NotifyOnShare. Explicit true or false values override the server default. Example: true.
results[].trace_collection_enabled	boolean	Whether per-job OpenTelemetry traces are collected for this content item. Traces are collected only when both this field and the server setting Applications.AllowTraceCollection are true. Example: false.
results[].owner_guid	string (uuid)	The unique identifier of the user who created this content item. Automatically assigned when the content is created. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
results[].content_url	string	The URL associated with this content. Computed from the associated GUID for this content. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
results[].dashboard_url	string	The URL within the Connect dashboard where this content can be configured. Computed from the GUID for this content. Example: https://posit-connect.company.com/connect/#/apps/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
results[].vanity_url	string	The vanity URL associated with this content item. Included in responses when the vanity URL is set and include=vanity_url is provided. Example: https://posit-connect.company.com/my-content/.
results[].app_role	string	The relationship of the accessing user to this content. A value of owner is returned for the content owner. editor indicates a collaborator. The viewer value is given to users who are permitted to view the content. A none role is returned for administrators who cannot view the content but are permitted to view its configuration. Computed at the time of the request. Example: owner.
results[].bookmarked	boolean|null	Indicates whether the requesting user has bookmarked this content item. Included in responses when include=bookmarked is provided. Example: true.
results[].schedules	[object]	Schedules associated with this content item. Included in responses when include=schedule is provided.
results[].schedules[].type	string	The schedule type. Example: rrule.
results[].schedules[].schedule	object	The recurrence rule in RFC5545 format.
results[].schedules[].schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
results[].schedules[].schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
results[].schedules[].schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
results[].schedules[].next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
results[].schedules[].email	boolean	Whether email notifications are enabled for this schedule. Example: false.
results[].schedules[].timezone	string	The timezone for this schedule. Example: America/New_York.
results[].schedules[].start_time	string (date-time)|null	The start time of the schedule window.
results[].schedules[].end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
results[].schedules[].last_run	object	Information about the last scheduled run.
results[].schedules[].last_run.job_key	string	The unique key of the job. Example: abc123xyz.
results[].schedules[].last_run.status	string	The status of the last run. Example: success.
results[].schedules[].last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
results[].schedules[].last_run.queued_time	string (date-time)|null	The time the run was queued.
results[].schedules[].last_run.start_time	string (date-time)	The time the run started.
results[].schedules[].last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
results[].schedules[].last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
results[].schedules[].last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.
results[].schedules[].variant	object	Variant information embedded in a schedule.
results[].schedules[].variant.key	string	The variant key. Example: default.
results[].schedules[].variant.name	string	The variant name. Example: Default Variant.
results[].schedules[].variant.is_default	boolean	Whether this is the default variant. Example: true.
results[].id	string	The internal numeric identifier of this content item. Example: 314.
results[].tags	[object]	Tags associated with this content item. Included in responses when include=tags is provided. Returns an empty array when content has no tags.
results[].tags[].id	string	The identifier for the tag. Example: 101.
results[].tags[].name	string	The name of the tag. Example: financial-statements.
results[].tags[].parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
results[].tags[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
results[].tags[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.
results[].owner	object	Basic details about the owner of this content item. Included in responses when include=owner is provided.
results[].owner.guid	string (uuid)	The owner’s unique identifier. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
results[].owner.username	string|null	The owner’s username. Example: jondoe.
results[].owner.first_name	string|null	The owner’s first name. Example: Jon.
results[].owner.last_name	string|null	The owner’s last name. Example: Doe.
results[].public_content_status	string|null	Validation status of public interactive content. When validation is required by licensing, this will be one of “ok”, “warning”, or “restricted”. If licensing does not require validation, it will be “unrestricted”; if licensing does not allow public interactive content, it will be “unlicensed”. If the app has not been made public, but public content is permitted, it will be “none”. Example: unrestricted.
warnings	[string]	An optional list of warning messages generated during query processing. Warnings indicate issues with the search query that did not prevent the search from completing, such as invalid filter values. When a filter value is invalid, the filter is ignored and results are returned unfiltered for that field. This field is omitted when there are no warnings. Example: ["Invalid value for 'published' filter: 'bogus'. Expected true or false"].

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Search for variants

GET /v1/search/variants

This endpoint searches for variants (report outputs). Variants are created when reports are rendered. A parameterized report may have multiple variants when it is rendered with different parameter values.

Authenticated access is required. Administrators can see public variants, and their own private variants, for all content, while other users can only see variants for content they own or have permissions to access.

Variant visibility

In addition to content-level permissions, variants have their own visibility settings:

• Public variants: Visible to all users who can access the parent content
• Private variants: Only visible to the variant owner, regardless of content permissions

ADHOC variants (temporary renders) are never returned in search results.

Pagination

This endpoint uses offset pagination. Requests can include query-string parameters for page_number and page_size to fetch different pages of results.

Parameters

Name	Type	Description
q	string
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
sort	string	The field to sort by.
order	string	The sort order: asc or desc.
include	string	A comma-separated list of additional information to include in the response. schedule: Include schedule information for each variant, including the schedule configuration and last run details.

Responses

200

200: Successful response.

Search results containing variants and pagination metadata.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The list of variants, paginated
results[].content_guid	string (uuid)	The GUID of the parent content item Example: abc123de-f456-7890-abcd-ef1234567890.
results[].content_name	string	The URL-friendly name of the parent content item Example: monthly-sales-report.
results[].content_title	string|null	The human-readable title of the parent content item Example: Monthly Sales Report.
results[].variant_key	string	The unique key identifying this variant Example: xyz789.
results[].variant_name	string	The human-readable name of the variant Example: West Region.
results[].is_default	boolean	Whether this is the default variant for the content Example: false.
results[].created_time	string (date-time)	The time this variant was created Example: 2025-06-15T09:00:00Z.
results[].render_time	string (date-time)|null	The time this variant was last rendered Example: 2026-01-26T08:00:00Z.
results[].failures	integer	The number of failed jobs (non-zero exit code) for this variant. When a failed:>= filter is used, this count is scoped to failures on or after the given timestamp. Example: 0.
results[].last_failed	string (date-time)|null	The time the most recent failed job completed for this variant. Null if no failures have occurred. When a failed:>= filter is used, this reflects only failures within the given time window. Example: 2026-02-01T12:00:00Z.
results[].skips	integer	The number of skipped scheduled jobs for this variant. When a skipped:>= filter is used, this count is scoped to skips on or after the given timestamp. Example: 0.
results[].last_skipped	string (date-time)|null	The scheduled time of the most recent skipped job for this variant. Null if no skips have occurred. When a skipped:>= filter is used, this reflects only skips within the given time window. Example: 2026-02-01T12:00:00Z.
results[].schedule	object	Schedule information for this variant. Omitted if no schedule exists.
results[].schedule.type	string	The schedule type. Example: rrule.
results[].schedule.schedule	object	The recurrence rule in RFC5545 format.
results[].schedule.schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
results[].schedule.schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
results[].schedule.schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
results[].schedule.next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
results[].schedule.email	boolean	Whether email notifications are enabled for this schedule. Example: false.
results[].schedule.timezone	string	The timezone for this schedule. Example: America/New_York.
results[].schedule.start_time	string (date-time)|null	The start time of the schedule window.
results[].schedule.end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
results[].schedule.last_run	object	Information about the last scheduled run.
results[].schedule.last_run.job_key	string	The unique key of the job. Example: abc123xyz.
results[].schedule.last_run.status	string	The status of the last run. Example: success.
results[].schedule.last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
results[].schedule.last_run.queued_time	string (date-time)|null	The time the run was queued.
results[].schedule.last_run.start_time	string (date-time)	The time the run started.
results[].schedule.last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
results[].schedule.last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
results[].schedule.last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Content Permissions

List permissions

GET /v1/content/{guid}/permissions

List the permissions for this content item. There will be one permission item for each user or group listed in the ACL for this content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

Defines the permission level that a user or group has been granted to a content item.

Name	Type	Description
id	string	The identifier for this permission entry. Example: 101.
content_guid	string (uuid)	The identifier of the content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
principal_guid	string (uuid)	The identifier of the principal (user or group) listed in the ACL. Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Add or update permission

POST /v1/content/{guid}/permissions

Upsert a user or group to the permissions for this content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when creating or updating a content permission item.

Name	Type	Description
principal_guid	string (uuid)	The identifier of the principal (user or group). Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.
send_email	boolean	Whether to send an email notification to the principal being added. Only applies when creating a new permission (POST); ignored on update (PUT). Defaults to false when not provided. Example: false.

Responses

200

200: Successful response.

Defines the permission level that a user or group has been granted to a content item.

Name	Type	Description
id	string	The identifier for this permission entry. Example: 101.
content_guid	string (uuid)	The identifier of the content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
principal_guid	string (uuid)	The identifier of the principal (user or group) listed in the ACL. Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.

201

201: Successful response.

Defines the permission level that a user or group has been granted to a content item.

Name	Type	Description
id	string	The identifier for this permission entry. Example: 101.
content_guid	string (uuid)	The identifier of the content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
principal_guid	string (uuid)	The identifier of the principal (user or group) listed in the ACL. Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get permission

GET /v1/content/{guid}/permissions/{id}

Get a single permission entry for the content item, given its ID.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

200

200: Successful response.

Defines the permission level that a user or group has been granted to a content item.

Name	Type	Description
id	string	The identifier for this permission entry. Example: 101.
content_guid	string (uuid)	The identifier of the content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
principal_guid	string (uuid)	The identifier of the principal (user or group) listed in the ACL. Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update permission

PUT /v1/content/{guid}/permissions/{id}

Update a permission entry for this content item.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Request body

The fields that can be specified when creating or updating a content permission item.

Name	Type	Description
principal_guid	string (uuid)	The identifier of the principal (user or group). Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.
send_email	boolean	Whether to send an email notification to the principal being added. Only applies when creating a new permission (POST); ignored on update (PUT). Defaults to false when not provided. Example: false.

Responses

200

200: Successful response.

Defines the permission level that a user or group has been granted to a content item.

Name	Type	Description
id	string	The identifier for this permission entry. Example: 101.
content_guid	string (uuid)	The identifier of the content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
principal_guid	string (uuid)	The identifier of the principal (user or group) listed in the ACL. Example: 62543474-5716-4423-92d1-b3a22163eb49.
principal_type	string	The type of principal. Example: user.
role	string	The level of access that the principal has been given to this content item. Example: viewer.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete permission

DELETE /v1/content/{guid}/permissions/{id}

Delete a single permission entry for the content item, given its ID.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Custom Documentation

Get custom documentation

GET /v1/system/documentation

Retrieve the custom documentation for your Posit Connect server, formatted using Markdown. Returns a 404 Not Found error if no custom documentation is configured.

Responses

200

200: Successful response.

The custom documentation for the Posit Connect server.

Name	Type	Description
content	string	The custom documentation content, formatted using Markdown.
created_time	string (date-time)	The time when the custom documentation was created.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Set custom documentation

POST /v1/system/documentation

Set the custom documentation for your Posit Connect server, formatted using Markdown. The maximum length for the provided documentation is 500000 characters. This action is only available to administrators. Returns a 204 No Content response if the documentation was successfully set.

Request body

The custom documentation for the Posit Connect server.

Name	Type	Description
content	string	The custom documentation content, formatted using Markdown.
created_time	string (date-time)	The time when the custom documentation was created.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete custom documentation

DELETE /v1/system/documentation

Delete the custom documentation for your Posit Connect server. This action is only available to administrators. Returns a 204 No Content response if the documentation was successfully deleted. Returns a 404 Not Found error if no custom documentation is configured.

Responses

204

204: Successful response.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Environment Permissions

List permissions

GET /v1/environments/{guid}/permissions

List the users and groups that have access to this execution environment. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

Provides details about the relationship between the execution environment and the user or group that has access to it.

Name	Type	Description
id	string	The internal identifier for this permission entry. Example: 101.
guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
environment_guid	string (uuid)	The identifier of the execution environment. Example: 62543474-5716-4423-92d1-b3a22163eb49.
user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Add permission

POST /v1/environments/{guid}/permissions

Grants a user or group access to this execution environment. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when adding permissions to an execution environment. Note that only one of user_guid or group_guid can be specified in a single request.

Name	Type	Description
user_guid	string (uuid)|null	The identifier of the user. Do not specify this field if you are adding a group. Example: 89a3c946-d73c-4781-8463-dd3cccff3fef.
group_guid	string (uuid)|null	The identifier of the group. Do not specify this field if you are adding a user. Example: 998f3356-96f0-48a2-9655-94334615fa5b.

Responses

200

200: Successful response.

Provides details about the relationship between the execution environment and the user or group that has access to it.

Name	Type	Description
id	string	The internal identifier for this permission entry. Example: 101.
guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
environment_guid	string (uuid)	The identifier of the execution environment. Example: 62543474-5716-4423-92d1-b3a22163eb49.
user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get permission

GET /v1/environments/{guid}/permissions/{permission_guid}

Get a single permission entry for the execution environment, given its GUID. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
permission_guid	string	Required.

Responses

200

200: Successful response.

Provides details about the relationship between the execution environment and the user or group that has access to it.

Name	Type	Description
id	string	The internal identifier for this permission entry. Example: 101.
guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
environment_guid	string (uuid)	The identifier of the execution environment. Example: 62543474-5716-4423-92d1-b3a22163eb49.
user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete permission

DELETE /v1/environments/{guid}/permissions/{permission_guid}

Removes access to this execution environment from a user or group. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
permission_guid	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Environments

List execution environments

GET /v1/environments

List all execution environments available to Posit Connect.

You must have administrator or publisher privileges to perform this action.

Responses

200

200: Successful response.

Array of objects:

An execution environment available to Posit Connect when Off Host Execution is enabled.

Name	Type	Description
id	string	The internal numeric identifier of this environment. Example: 314.
guid	string (uuid)	The unique identifier of this environment to be used with REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was last updated. Example: 2006-01-02T15:04:05-07:00.
title	string|null	A human readable title for this environment. Example: Project Alpha (R 4.1.1, Python 3.10).
description	string|null	A human readable description of this environment. Example: This is my description of the environment.
cluster_name	string	The cluster identifier for this environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
name	string	The container image that will be used when executing content with this environment. Example: ghcr.io/rstudio/content-base:r4.1.3-py3.10.4-ubuntu1804.
environment_type	string	The type of environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
matching	string	This field indicates how environments can be considered for selection when Posit Connect is choosing a compatible environment to use when executing content. any (the default) indicates that the image can be selected by Connect automatically, or targeted in the bundle’s manifest. exact indicates the image must be explicitly asked for in the bundle’s manifest. none indicates that the image should never be selected by Posit Connect. Example: any.
supervisor	string|null	The path to the script or command that should be used as the program supervisor when executing content with this environment. Example: /usr/local/bin/supervisor.sh.
managed_by	string|null	Indicates which system manages this environment. A null value indicates the environment is not externally managed.
python	object	The available Python installations in this environment.
python.installations	[object]	The list of language installations.
python.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
python.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
quarto	object	The available Quarto installations in this environment.
quarto.installations	[object]	The list of language installations.
quarto.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
quarto.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
r	object	The available R installations in this environment.
r.installations	[object]	The list of language installations.
r.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
r.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
tensorflow	object	The available TensorFlow installations in this environment.
tensorflow.installations	[object]	The list of language installations.
tensorflow.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
tensorflow.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
volume_mounts	[object]	The volume mounts for this environment.
volume_mounts[].source	object	The source specification for this mount.
volume_mounts[].source.volume_type	string	The type of volume. Example: nfs.
volume_mounts[].source.nfs_host	string|null	The NFS host. Required when volume_type is nfs.
volume_mounts[].source.nfs_export_path	string|null	The NFS export path. Required when volume_type is nfs.
volume_mounts[].source.pvc_name	string|null	The PersistentVolumeClaim name. Required when volume_type is pvc.
volume_mounts[].target	object	The target specification for this mount.
volume_mounts[].target.path	string	The mount path inside the container. Example: /mnt/data.
volume_mounts[].target.read_only	boolean|null	Whether the volume is mounted read-only. Example: false.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create execution environment

POST /v1/environments

Create a new execution environment.

You must have administrator privileges to perform this action.

Request body

The fields that can be specified when creating an environment.

Name	Type	Description
title	string|null	A human readable title for this environment. Example: Project Alpha (R 4.1.1, Python 3.10).
description	string|null	A human readable description of this environment. Example: This is my description of the environment.
cluster_name	string	The cluster identifier for this environment. The value must be “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
name	string	The container image that will be used when executing content with this environment. Example: ghcr.io/rstudio/content-base:r4.1.3-py3.10.4-ubuntu1804.
matching	string|null	This field indicates how environments can be considered for selection when Posit Connect is choosing a compatible environment to use when executing content. any (the default) indicates that the image can be selected by Connect automatically, or targeted in the bundle’s manifest. exact indicates the image must be explicitly asked for in the bundle’s manifest. none indicates that the image should never be selected by Posit Connect. Example: any.
supervisor	string|null	The path to the script or command that should be used as the program supervisor when executing content with this environment. Example: /usr/local/bin/supervisor.sh.
python	object	The available Python installations in this environment.
python.installations	[object]	The list of language installations.
python.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
python.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
quarto	object	The available Quarto installations in this environment.
quarto.installations	[object]	The list of language installations.
quarto.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
quarto.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
r	object	The available R installations in this environment.
r.installations	[object]	The list of language installations.
r.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
r.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
tensorflow	object	The available TensorFlow installations in this environment.
tensorflow.installations	[object]	The list of language installations.
tensorflow.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
tensorflow.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
volume_mounts	[object]	The volume mounts for this environment.
volume_mounts[].source	object	The source specification for this mount.
volume_mounts[].source.volume_type	string	The type of volume. Example: nfs.
volume_mounts[].source.nfs_host	string|null	The NFS host. Required when volume_type is nfs.
volume_mounts[].source.nfs_export_path	string|null	The NFS export path. Required when volume_type is nfs.
volume_mounts[].source.pvc_name	string|null	The PersistentVolumeClaim name. Required when volume_type is pvc.
volume_mounts[].target	object	The target specification for this mount.
volume_mounts[].target.path	string	The mount path inside the container. Example: /mnt/data.
volume_mounts[].target.read_only	boolean|null	Whether the volume is mounted read-only. Example: false.

Responses

200

200: Successful response.

An execution environment available to Posit Connect when Off Host Execution is enabled.

Name	Type	Description
id	string	The internal numeric identifier of this environment. Example: 314.
guid	string (uuid)	The unique identifier of this environment to be used with REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was last updated. Example: 2006-01-02T15:04:05-07:00.
title	string|null	A human readable title for this environment. Example: Project Alpha (R 4.1.1, Python 3.10).
description	string|null	A human readable description of this environment. Example: This is my description of the environment.
cluster_name	string	The cluster identifier for this environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
name	string	The container image that will be used when executing content with this environment. Example: ghcr.io/rstudio/content-base:r4.1.3-py3.10.4-ubuntu1804.
environment_type	string	The type of environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
matching	string	This field indicates how environments can be considered for selection when Posit Connect is choosing a compatible environment to use when executing content. any (the default) indicates that the image can be selected by Connect automatically, or targeted in the bundle’s manifest. exact indicates the image must be explicitly asked for in the bundle’s manifest. none indicates that the image should never be selected by Posit Connect. Example: any.
supervisor	string|null	The path to the script or command that should be used as the program supervisor when executing content with this environment. Example: /usr/local/bin/supervisor.sh.
managed_by	string|null	Indicates which system manages this environment. A null value indicates the environment is not externally managed.
python	object	The available Python installations in this environment.
python.installations	[object]	The list of language installations.
python.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
python.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
quarto	object	The available Quarto installations in this environment.
quarto.installations	[object]	The list of language installations.
quarto.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
quarto.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
r	object	The available R installations in this environment.
r.installations	[object]	The list of language installations.
r.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
r.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
tensorflow	object	The available TensorFlow installations in this environment.
tensorflow.installations	[object]	The list of language installations.
tensorflow.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
tensorflow.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
volume_mounts	[object]	The volume mounts for this environment.
volume_mounts[].source	object	The source specification for this mount.
volume_mounts[].source.volume_type	string	The type of volume. Example: nfs.
volume_mounts[].source.nfs_host	string|null	The NFS host. Required when volume_type is nfs.
volume_mounts[].source.nfs_export_path	string|null	The NFS export path. Required when volume_type is nfs.
volume_mounts[].source.pvc_name	string|null	The PersistentVolumeClaim name. Required when volume_type is pvc.
volume_mounts[].target	object	The target specification for this mount.
volume_mounts[].target.path	string	The mount path inside the container. Example: /mnt/data.
volume_mounts[].target.read_only	boolean|null	Whether the volume is mounted read-only. Example: false.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get execution environment details

GET /v1/environments/{guid}

Get detailed information about a specific execution environment.

You must have administrator or publisher privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

An execution environment available to Posit Connect when Off Host Execution is enabled.

Name	Type	Description
id	string	The internal numeric identifier of this environment. Example: 314.
guid	string (uuid)	The unique identifier of this environment to be used with REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was last updated. Example: 2006-01-02T15:04:05-07:00.
title	string|null	A human readable title for this environment. Example: Project Alpha (R 4.1.1, Python 3.10).
description	string|null	A human readable description of this environment. Example: This is my description of the environment.
cluster_name	string	The cluster identifier for this environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
name	string	The container image that will be used when executing content with this environment. Example: ghcr.io/rstudio/content-base:r4.1.3-py3.10.4-ubuntu1804.
environment_type	string	The type of environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
matching	string	This field indicates how environments can be considered for selection when Posit Connect is choosing a compatible environment to use when executing content. any (the default) indicates that the image can be selected by Connect automatically, or targeted in the bundle’s manifest. exact indicates the image must be explicitly asked for in the bundle’s manifest. none indicates that the image should never be selected by Posit Connect. Example: any.
supervisor	string|null	The path to the script or command that should be used as the program supervisor when executing content with this environment. Example: /usr/local/bin/supervisor.sh.
managed_by	string|null	Indicates which system manages this environment. A null value indicates the environment is not externally managed.
python	object	The available Python installations in this environment.
python.installations	[object]	The list of language installations.
python.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
python.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
quarto	object	The available Quarto installations in this environment.
quarto.installations	[object]	The list of language installations.
quarto.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
quarto.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
r	object	The available R installations in this environment.
r.installations	[object]	The list of language installations.
r.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
r.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
tensorflow	object	The available TensorFlow installations in this environment.
tensorflow.installations	[object]	The list of language installations.
tensorflow.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
tensorflow.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
volume_mounts	[object]	The volume mounts for this environment.
volume_mounts[].source	object	The source specification for this mount.
volume_mounts[].source.volume_type	string	The type of volume. Example: nfs.
volume_mounts[].source.nfs_host	string|null	The NFS host. Required when volume_type is nfs.
volume_mounts[].source.nfs_export_path	string|null	The NFS export path. Required when volume_type is nfs.
volume_mounts[].source.pvc_name	string|null	The PersistentVolumeClaim name. Required when volume_type is pvc.
volume_mounts[].target	object	The target specification for this mount.
volume_mounts[].target.path	string	The mount path inside the container. Example: /mnt/data.
volume_mounts[].target.read_only	boolean|null	Whether the volume is mounted read-only. Example: false.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update an execution environment

PUT /v1/environments/{guid}

Update a specific execution environment.

You must have administrator privileges to perform this action.

Environments managed by a configuration file cannot be updated via the API.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when updating an environment.

Name	Type	Description
title	string|null	A human readable title for this environment. Example: Project Alpha (R 4.1.1, Python 3.10).
description	string|null	A human readable description of this environment. Example: This is my description of the environment.
matching	string|null	This field indicates how environments can be considered for selection when Posit Connect is choosing a compatible environment to use when executing content. any (the default) indicates that the image can be selected by Connect automatically, or targeted in the bundle’s manifest. exact indicates the image must be explicitly asked for in the bundle’s manifest. none indicates that the image should never be selected by Posit Connect. Example: any.
supervisor	string|null	The path to the script or command that should be used as the program supervisor when executing content with this environment. Example: /usr/local/bin/supervisor.sh.
python	object	The available Python installations in this environment.
python.installations	[object]	The list of language installations.
python.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
python.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
quarto	object	The available Quarto installations in this environment.
quarto.installations	[object]	The list of language installations.
quarto.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
quarto.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
r	object	The available R installations in this environment.
r.installations	[object]	The list of language installations.
r.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
r.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
tensorflow	object	The available TensorFlow installations in this environment.
tensorflow.installations	[object]	The list of language installations.
tensorflow.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
tensorflow.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
volume_mounts	[object]	The volume mounts for this environment.
volume_mounts[].source	object	The source specification for this mount.
volume_mounts[].source.volume_type	string	The type of volume. Example: nfs.
volume_mounts[].source.nfs_host	string|null	The NFS host. Required when volume_type is nfs.
volume_mounts[].source.nfs_export_path	string|null	The NFS export path. Required when volume_type is nfs.
volume_mounts[].source.pvc_name	string|null	The PersistentVolumeClaim name. Required when volume_type is pvc.
volume_mounts[].target	object	The target specification for this mount.
volume_mounts[].target.path	string	The mount path inside the container. Example: /mnt/data.
volume_mounts[].target.read_only	boolean|null	Whether the volume is mounted read-only. Example: false.

Responses

200

200: Successful response.

An execution environment available to Posit Connect when Off Host Execution is enabled.

Name	Type	Description
id	string	The internal numeric identifier of this environment. Example: 314.
guid	string (uuid)	The unique identifier of this environment to be used with REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this environment was last updated. Example: 2006-01-02T15:04:05-07:00.
title	string|null	A human readable title for this environment. Example: Project Alpha (R 4.1.1, Python 3.10).
description	string|null	A human readable description of this environment. Example: This is my description of the environment.
cluster_name	string	The cluster identifier for this environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
name	string	The container image that will be used when executing content with this environment. Example: ghcr.io/rstudio/content-base:r4.1.3-py3.10.4-ubuntu1804.
environment_type	string	The type of environment. The value is always “Kubernetes” when Off Host Execution is enabled. Example: Kubernetes.
matching	string	This field indicates how environments can be considered for selection when Posit Connect is choosing a compatible environment to use when executing content. any (the default) indicates that the image can be selected by Connect automatically, or targeted in the bundle’s manifest. exact indicates the image must be explicitly asked for in the bundle’s manifest. none indicates that the image should never be selected by Posit Connect. Example: any.
supervisor	string|null	The path to the script or command that should be used as the program supervisor when executing content with this environment. Example: /usr/local/bin/supervisor.sh.
managed_by	string|null	Indicates which system manages this environment. A null value indicates the environment is not externally managed.
python	object	The available Python installations in this environment.
python.installations	[object]	The list of language installations.
python.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
python.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
quarto	object	The available Quarto installations in this environment.
quarto.installations	[object]	The list of language installations.
quarto.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
quarto.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
r	object	The available R installations in this environment.
r.installations	[object]	The list of language installations.
r.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
r.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
tensorflow	object	The available TensorFlow installations in this environment.
tensorflow.installations	[object]	The list of language installations.
tensorflow.installations[].version	string	The semantic version of the interpreter. Example: 3.6.3.
tensorflow.installations[].path	string	The absolute path to the interpreter’s executable. Example: /opt/R/3.6.3/bin/R.
volume_mounts	[object]	The volume mounts for this environment.
volume_mounts[].source	object	The source specification for this mount.
volume_mounts[].source.volume_type	string	The type of volume. Example: nfs.
volume_mounts[].source.nfs_host	string|null	The NFS host. Required when volume_type is nfs.
volume_mounts[].source.nfs_export_path	string|null	The NFS export path. Required when volume_type is nfs.
volume_mounts[].source.pvc_name	string|null	The PersistentVolumeClaim name. Required when volume_type is pvc.
volume_mounts[].target	object	The target specification for this mount.
volume_mounts[].target.path	string	The mount path inside the container. Example: /mnt/data.
volume_mounts[].target.read_only	boolean|null	Whether the volume is mounted read-only. Example: false.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete an execution environment

DELETE /v1/environments/{guid}

Delete a specific execution environment.

You must have administrator privileges to perform this action.

Environments managed by a configuration file cannot be deleted via the API.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Examples

List examples

GET /v1/examples

Warning

This endpoint is deprecated.

List all examples.

This endpoint is deprecated.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get example thumbnail

GET /v1/examples/{name}/thumbnail

Warning

This endpoint is deprecated.

Download the thumbnail image for the named example.

This endpoint is deprecated.

Parameters

Name	Type	Description
name	string	Required.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Download example

GET /v1/examples/{name}/zip

Warning

This endpoint is deprecated.

Download a ZIP archive containing the named example.

This endpoint is deprecated.

Parameters

Name	Type	Description
name	string	Required.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Feature Usage

Provides details about all tracked features.

GET /v1/feature-usage

This endpoint returns details about all tracked features. This endpoint requires publisher access. The response is not paginated. All flags are returned.

Responses

200

200: Successful response.

Array of objects:

Details about a tracked feature.

Name	Type	Description
name	string	Name of the feature flag.
used	boolean	Whether or not this feature has been used.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Groups

List content for which a group with given GUID has access to

GET /v1/experimental/groups/{guid}/content

This endpoint takes a group GUID and returns a list of content items with access control lists that the given group is listed on. This includes content accessible only by specific users or groups that include the given group, as well as content accessible by anyone or only logged-in users that includes the given group as a collaborator.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

Content item with access control details for a group.

Name	Type	Description
content_guid	string (uuid)	The unique identifier of the content item. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
content_name	string	The name of the content item.
content_title	string	The title of the content item.
access_type	string	The access type of the content item. Example: acl.
permissions	[object]	List of principals (users and groups) with access to the content. The owner is listed as author and is always present.
permissions[].principal_guid	string (uuid)	The identifier of the principal (user or group) with access to the content. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
permissions[].principal_name	string	The name of the principal (user or group) with access to the content.
permissions[].principal_role	string	The role of the principal (user or group) with access to the content. Example: author.
permissions[].principal_type	string	The type of the principal (user or group) with access to the content. Example: user.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List or search for group details

GET /v1/groups

This endpoint lists or searches for local groups.

• For a prefix search, results are sorted based on similarity to the prefix. A prefix search ignores asc_order.
• The prefix can also be an exact match for the group’s DN (for LDAP) or the auth provider’s unique ID for the group, if any.
• For a non-prefix search, results are sorted by group name.

This endpoint is available only when groups are enabled in Posit Connect and it will return an error otherwise.

This endpoint uses offset pagination. Requests can include query-string parameters for page_number and page_size to fetch different pages of results.

Parameters

Name	Type	Description
prefix	string
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
asc_order	boolean	Whether results are in ascending order.
page_size	integer

Responses

200

200: Successful response.

The groups list with paging information.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The groups list
results[].guid	string (uuid)	The unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
results[].name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
results[].key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
results[].scopes	[string]	The scopes granted to this service token.
results[].created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
results[].active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create a group from caller-supplied details (Password, PAM, OAuth2, SAML, Proxied)

POST /v1/groups

This endpoint creates the given group.

• This endpoint is available only when groups are enabled in Posit Connect and only for Password, PAM, OAuth2, SAML and Proxied authentication.
• Publisher or administrator access is required to create groups.

Request body

The fields that can be specified when creating a group.

Name	Type	Description
name	string	The group’s desired name Example: marketing.
unique_id	string	Applies to SAML, OAuth2 and Proxied authentication when the setting GroupsByUniqueId is enabled. This field must not be present otherwise.
gid	integer|null	The POSIX Group ID (GID) for current user execution. Only administrators can set this field, and only when using SAML or OAuth2 authentication. Must be a positive integer and unique across all groups. Example: 1001.

Responses

200

200: Successful response.

A group object.

Name	Type	Description
guid	string (uuid)	The unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create a group using details from a remote authentication provider (LDAP)

PUT /v1/groups

This endpoint creates the given group on the Posit Connect server.

• This endpoint is used only for LDAP authentication. Password, PAM, SAML, OAuth2 and Proxied authentication providers should use the POST /v1/groups endpoint.
• Publisher or administrator access is required to access this endpoint.
• Group members will be automatically populated from the LDAP server.

Group Creation Workflow on LDAP

The API lets you identify an existing group in the LDAP system and create a corresponding group on Posit Connect. This is a two-step process:

• Use the GET /v1/groups/remote endpoint. This endpoint will return a list of potential matching groups in LDAP. A group that does not exist in Posit Connect will lack a guid. Note the temp_ticket for the desired group.
• Use this PUT endpoint with the temp_ticket to create a corresponding group on Posit Connect.

The Cookbook contains a recipe on Creating a Group Using a Remote Authentication Provider (LDAP) which demonstrates this workflow using the R and Python SDKs.

Request body

The fields that must be specified when creating a remote group.

Name temp_ticket	Type string	Description | ========================================================+ The temporary ticket used for creating a group on the | Posit Connect server. It is obtained from the | GET /v1/groups/remote endpoint.

Responses

200

200: Successful response.

A group object.

Name	Type	Description
guid	string (uuid)	The unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get group member details

GET /v1/groups/{group_guid}/members

This endpoint gets the group member details. Group member enumeration is currently not supported for LDAP.

• This endpoint is available only when groups are enabled in Posit Connect and only for Password, PAM, OAuth2, SAML and Proxied authentication.
• The email field is not populated for non-admins when Server.HideEmailAddresses is enabled.

Parameters

Name	Type	Description
group_guid	string	Required.

Responses

200

200: Successful response.

The group members list with paging information.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The group members list
results[].email	string	The user’s email. Example: jon.doe@example.com.
results[].username	string	The user’s username. Example: jondoe.
results[].first_name	string	The user’s first name. Example: Jon.
results[].last_name	string	The user’s last name. Example: Doe.
results[].user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
results[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
results[].confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
results[].locked	boolean	Whether or not the user is locked. Example: false.
results[].external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
results[].guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Add a group member

POST /v1/groups/{group_guid}/members

This endpoint adds a user to a group.

• This endpoint is available only when groups are enabled in Posit Connect and only for Password, PAM, OAuth2, SAML and Proxied authentication. If the auth provider is configured to provide group membership information, then it is not possible to add/remove members via this API.
• Administrator access is required to modify a group you do not own.

Parameters

Name	Type	Description
group_guid	string	Required.

Request body

The fields that must be specified when adding a member to a group.

Name	Type	Description
user_guid	string (uuid)	The user’s unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Remove a group member

DELETE /v1/groups/{group_guid}/members/{user_guid}

This endpoint removes a user from a group.

• This endpoint is available only when groups are enabled in Posit Connect and only for Password, PAM, OAuth2, SAML and Proxied authentication. If the auth provider is configured to provide group membership information, then it is not possible to add/remove members via this API.
• Administrator access is required to remove a user from a group you do not own, but no special access is needed to remove yourself from a group.

Parameters

Name	Type	Description
group_guid	string	Required.
user_guid	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get group details

GET /v1/groups/{guid}

Get detailed information on a specific group.

This endpoint is available only when groups are enabled in Posit Connect.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

A group object.

Name	Type	Description
guid	string (uuid)	The unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Modify a group name or owner (Password, PAM, OAuth2, SAML, Proxied)

POST /v1/groups/{guid}

This endpoint modifies the given group.

• This endpoint is available only when groups are enabled in Posit Connect and only for Password, PAM, OAuth2, SAML and Proxied authentication.
• Publisher or administrator access is required to modify groups.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when updating a group.

Object

Responses

200

200: Successful response.

A group object.

Name	Type	Description
guid	string (uuid)	The unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update a group (partial update)

PATCH /v1/groups/{guid}

This endpoint updates the specified fields of a group. Only fields included in the request body will be modified; omitted fields remain unchanged.

This endpoint requires groups to be enabled via the Authorization.UserGroups setting. Returns a 400 error if groups are disabled.

Field availability by authentication provider

Not all fields can be modified with all authentication providers:

Field	Password	PAM	LDAP	SAML	OAuth2	Proxied
name	✓	✓	✗	✓	✓	✓
owner_guid	✓¹	✓¹	✗	Configurable²	Configurable²	Configurable²
gid	✗	✗	✓	✓	✓	✗

¹ Password and PAM groups are managed locally in Connect and require an owner to manage group membership. Ownership can be transferred to another user but cannot be cleared.

² Behavior depends on the GroupsAutoProvision setting. When enabled, owners cannot be assigned or transferred, but existing owners can be cleared. When disabled, owners can be assigned or transferred but not cleared (same as Password and PAM).

Authorization requirements

Field	Required role
name	Group owner or administrator
owner_guid	Group owner or administrator
gid	Administrator only

Caution: When using SAML or OAuth2 with GroupsAutoProvision enabled but GroupsByUniqueId disabled, renaming a group in the identity provider creates a new group in Connect. The original group becomes orphaned but retains its gid. To transfer the gid to the new group, either delete the old group or set its gid to null, then set the gid on the new group.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when partially updating a group.

Name	Type	Description
name	string|null	The group’s new name. Cannot be empty or null, and must be at most 4096 characters. Names must be unique, except for SAML, OAuth2, and Proxied authentication when GroupsByUniqueId is enabled. Example: engineering.
owner_guid	string (uuid)|null	The new owner’s unique identifier. Must reference an existing user who is not a viewer. Can be set to null to remove the owner for SAML, OAuth2, and Proxied authentication when GroupsAutoProvision is enabled. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
gid	integer|null	The POSIX Group ID (GID) for current user execution. Must be a positive integer and unique across all groups. Set to null to remove the GID. Example: 1001.

Responses

200

200: Successful response.

A group object.

Name	Type	Description
guid	string (uuid)	The unique identifier Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete a group

DELETE /v1/groups/{guid}

Delete the given group.

• This endpoint can be used only when groups are enabled in Posit Connect and will return an error otherwise.
• Administrator access is required to delete a group you do not own.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Search for group details from a remote provider

GET /v1/groups/remote

This endpoint is used to support operations against groups not managed by Connect, such as creating LDAP groups. See GET /v1/groups for listing groups on Posit Connect.

This endpoint searches for groups on Posit Connect and on your LDAP system.

Results are sorted based on similarity to the prefix.

• This endpoint can be used only by LDAP authentication and will return an error otherwise.
• Publisher or administrator access is required to access this endpoint.

Parameters

Name	Type	Description
prefix	string
limit	integer

Responses

200

200: Successful response.

The remote group search results with paging information.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The groups list
results[].name	string	The group name Example: accounting.
results[].guid	string (uuid)|null	The group’s unique identifier in RFC4122 format. When a group does not exist in the Posit Connect server, this property will be null. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
results[].temp_ticket	string	This value is for actions that require a temp_ticket, such as adding an LDAP group to the Connect server.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Instrumentation

Get all content hits

GET /v1/instrumentation/content/hits

This endpoint returns content usage information for all content types, also known as hits, where hits are individual activity events such as content visits or requests to APIs hosted on Posit Connect.

This endpoint requires administrator or publisher access. Publishers can query visits data for content they own or are a collaborator on.

Filtering of results:

There are several ways the result set can be filtered by the server before being sent back within the API response. If multiple filters are in effect, they will be logically ANDed together.

Implicit filtering

If the user calling the endpoint is a publisher, the data returned will be limited to the content owned by the user.

Time windows

This API accepts optional from and to timestamps to define a window of interest. If from is not specified, it is assumed to be before the earliest recorded information. If to is not specified, it is assumed to be “now”.

Any content hit activity that falls inclusively within the time window will be part of the result set.

Responses

The response of a call will contain zero or more data records representing a hit by a user to a piece of content. As opposed to other instrumentation API endpoints, this API is better suited to consume large amounts of unfiltered content activity records, to later be analysed and processed by the consumer.

Parameters

Name	Type	Description
content_guid	string
from	string
to	string

Responses

200

200: Successful response.

Array of objects:

A content hit activity record.

Name	Type	Description
id	string	The ID of the activity record. Example: 33.
user_guid	string (uuid)|null	The GUID of the user that visited the content. May be null when the content does not require a user session. Example: 08e3a41d-1f8e-47f2-8855-f05ea3b0d4b2.
content_guid	string (uuid)	The GUID of the content this activity pertains to. Example: bd1d2285-6c80-49af-8a83-a200effe3cb3.
timestamp	string (date-time)	The timestamp (RFC3339) when the user visited the content. Example: 2018-09-15T18:00:00-05:00.
data	object	Additional data about the content hit.
data.path	string|null	The path consumed for this hit event. Example: /summary.
data.query	string|null	The query string for this hit event. Example: view_hit_source=email.
data.user_agent	string|null	The user agent registered for this hit event. Example: Mozilla/5.0.
data.sec_fetch_dest	string|null	The value of the Sec-Fetch-Dest HTTP header. Common values: document, iframe, empty.
data.sec_fetch_site	string|null	The value of the Sec-Fetch-Site HTTP header. Common values: same-origin, same-site, cross-site, none.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get content visits

GET /v1/instrumentation/content/visits

This endpoint returns a portion of the visit (or “hits”) information for all content types other than Shiny applications. The results returned include paging details that can be used to navigate the information this endpoint returns.

The information returned is based on data collected by Posit Connect as users visit content in the dashboard or make requests to applications or APIs hosted on Connect.

Important notes

In the past there were issues with how visits were recorded that caused extra entries to be stored under certain circumstances. These will affect analyses that interpret visit counts. Entries that were recorded before issues were addressed are not returned by default. If you desire these records, specify the min_data_version filter with a value of 0 (the default value is 3).

This endpoint requires administrator or publisher access. Publishers can query visits data for content they own or are a collaborator on.

Filtering of results:

There are several ways the result set can be filtered by the server before being sent back within the API response. If multiple filters are in effect, they will be logically ANDed together.

Implicit filtering

If the user calling the endpoint is a publisher, the data returned will be limited to the content owned by the user.

Time windows

This API accepts optional from and to timestamps to define a window of interest. If from is not specified, it is assumed to be before the earliest recorded information. If to is not specified, it is assumed to be “now”.

Any visit to content that falls inclusively within the time window will be part of the result set.

Responses

The response of a call will contain zero or more data records representing a visit by a user to a piece of content. No more than limit records will be returned. Multiple requests of this endpoint are typically required to retrieve the complete result set from the server. To facilitate this, each response includes a paging object containing full URL links which can be requested to iteratively move forward or backward through multiple response pages.

Parameters

Name	Type	Description
content_guid	string
min_data_version	integer
user_agent	string
from	string
to	string
limit	integer
previous	string
next	string
asc_order	boolean

Responses

200

200: Successful response.

Content visit results with keyset pagination.

Name	Type	Description
results	[object]	The content visit logs.
results[].content_guid	string (uuid)	The GUID of the content this visit pertains to. Example: bd1d2285-6c80-49af-8a83-a200effe3cb3.
results[].user_guid	string (uuid)|null	The GUID of the user that visited the content. May be null when the content does not require a user session. Example: 08e3a41d-1f8e-47f2-8855-f05ea3b0d4b2.
results[].variant_key	string|null	The key of the variant the user visited. Null for static content. Example: HidI2Kwq.
results[].time	string (date-time)	The timestamp (RFC3339) when the user visited the content. Example: 2018-09-15T18:00:00-05:00.
results[].rendering_id	string|null	The ID of the rendering the user visited. Null for static content. Example: 7.
results[].bundle_id	string|null	The ID of the particular bundle used. Example: 33.
results[].path	string|null	The path requested by the user. Example: /logs.
results[].data_version	integer	The data version the record was recorded with. Example: 1.
results[].user_agent	string|null	The user agent that made the request. Example: Mozilla/5.0.
paging	object	Paging information for navigating result sets.
paging.first	string|null	A full URL of the first page of results. Null if the current response is the first page.
paging.previous	string|null	A full URL of the previous page of results. Null if the current response is the first page.
paging.next	string|null	A full URL of the next page of results. Null if the current response is the last page.
paging.last	string|null	A full URL of the last page of results. Null if the current response is the last page.
paging.cursors	object	Cursor values for navigating between pages.
paging.cursors.previous	string|null	A cursor ID that can be used with the previous query parameter to get the previous page of results. Example: 23948901087.
paging.cursors.next	string|null	A cursor ID that can be used with the next query parameter to get the next page of results. Example: 23948901087.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get Shiny app usage

GET /v1/instrumentation/shiny/usage

This endpoint returns a portion of the Shiny application usage information, as well as paging details that can be used to navigate that information.

The information returned is based on data collected by Posit Connect as users visit Shiny applications. Because of how visits are detected, end times will be slightly inflated by a reconnect timeout, generally around 15 seconds.

Important notes

Prior to the release of this API, there was an issue with how visits were recorded that caused extra entries to be stored. These will affect analyses that interpret visit counts or durations. Entries that were recorded before the issue was addressed are not returned by default. If you desire these records, specify the min_data_version filter with a value of 0.

• Because of how visits are detected, end times will be slightly inflated by the currently configured client reconnect timeout, which defaults to 15 seconds. The ending time may also be affected by connect and read timeout settings.

  The Shiny Application Events section of the Posit Connect Admin Guide has more details about how these events are collected.

• This endpoint requires administrator or publisher access. Publishers can query Shiny usage data for content they own or are a collaborator on.

Filtering of results:

There are several ways the result set can be filtered by the server before being sent back within the API response. If multiple filters are in effect, they will be logically ANDed together.

Implicit filtering

If the user calling the endpoint is a publisher, the data returned will be limited to those applications owned by the user.

Time windows

This API accepts optional from and to timestamps to define a window of interest. If from is not specified, it is assumed to be before the earliest recorded information. If to is not specified, it is assumed to be “now”.

Any visit to content that falls inclusively within the time window will be part of the result set.

Responses

The response of a call will contain zero or more data records representing a session by a user of a Shiny application. No more than limit records will be returned. Multiple requests of this endpoint are typically required to retrieve the complete result set from the server. To facilitate this, each response includes a paging object containing full URL links which can be requested to iteratively move forward or backward through multiple response pages.

Parameters

Name	Type	Description
content_guid	string
min_data_version	integer
from	string
to	string
limit	integer
previous	string
next	string
asc_order	boolean

Responses

200

200: Successful response.

Shiny application usage results with keyset pagination.

Name	Type	Description
results	[object]	The Shiny application usage logs.
results[].content_guid	string (uuid)	The GUID of the Shiny application this usage record pertains to. Example: bd1d2285-6c80-49af-8a83-a200effe3cb3.
results[].user_guid	string (uuid)|null	The GUID of the user that visited the application. May be null if the user cannot be determined. Example: 08e3a41d-1f8e-47f2-8855-f05ea3b0d4b2.
results[].started	string (date-time)	The timestamp (RFC3339) when the user opened the application. Example: 2018-09-15T18:00:00-05:00.
results[].ended	string (date-time)|null	The timestamp (RFC3339) when the user left the application. Example: 2018-09-15T18:01:00-05:00.
results[].data_version	integer	The data version the record was recorded with. Example: 1.
paging	object	Paging information for navigating result sets.
paging.first	string|null	A full URL of the first page of results. Null if the current response is the first page.
paging.previous	string|null	A full URL of the previous page of results. Null if the current response is the first page.
paging.next	string|null	A full URL of the next page of results. Null if the current response is the last page.
paging.last	string|null	A full URL of the last page of results. Null if the current response is the last page.
paging.cursors	object	Cursor values for navigating between pages.
paging.cursors.previous	string|null	A cursor ID that can be used with the previous query parameter to get the previous page of results. Example: 23948901087.
paging.cursors.next	string|null	A cursor ID that can be used with the next query parameter to get the next page of results. Example: 23948901087.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Jobs

Get jobs

GET /v1/content/{guid}/jobs

Get the list of jobs for a given piece of content. This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

A job record representing a content execution.

Name	Type	Description
id	string	The job identifier. Example: 54.
ppid	string|null	The job’s parent process identifier. Example: 20253.
pid	string	The job’s process identifier. Example: 20253.
key	string	The job’s unique key identifier. Example: tHawGvHZTosJA2Dx.
remote_id	string|null	The job’s identifier for off-host execution configurations. Example: S3ViZXJuZXRlczpyZW5kZXItci1tYXJrZG93bi1zaXRlLWtnODJo.
app_id	string	This field is deprecated and has been renamed to content_id. Example: 54.
content_id	string	The identifier for this job’s parent content. Example: 54.
content_guid	string	The unique identifier for this job’s content. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
variant_id	string	The identifier of the variant owning this job. Example: 54.
variant_key	string	The key of the variant owning this job. May be empty if the variant is no longer available. Example: HidI2Kwq.
bundle_id	string	The identifier of a content bundle linked to this job. Example: 54.
start_time	string (date-time)	The timestamp (RFC3339) indicating when this job started. Example: 2006-01-02T15:04:05-07:00.
end_time	string (date-time)|null	The timestamp (RFC3339) indicating when this job finished. Example: 2006-01-02T15:04:05-07:00.
last_heartbeat_time	string (date-time)|null	The timestamp (RFC3339) indicating the last time this job was observed to be running. Example: 2006-01-02T15:04:05-07:00.
queued_time	string (date-time)|null	The timestamp (RFC3339) indicating when this job was added to the queue to be processed. Only scheduled reports will present a value for this field. Example: 2006-01-02T15:04:05-07:00.
queue_name	string|null	The name of the queue which processes the job. Only scheduled reports will present a value for this field. Example: default.
tag	string	A tag to identify the nature of the job. It can be one of unknown, build_report, build_site, build_jupyter, packrat_restore, python_restore, configure_report, run_app, run_api, run_tensorflow, run_python_api, run_dash_app, run_streamlit, run_bokeh_app, run_panel_app, run_fastapi_app, run_gradio_app, run_pyshiny_app, render_shiny, run_voila_app, testing, git, val_py_ext_pkg, val_r_ext_pkg, val_r_install. Example: build_report.
exit_code	integer|null	The job’s exit code. Present only when job is finished. Example: 0.
error	string|null	The error message if the job failed due to an unexpected server error.
status	integer	The current status of the job. It can be one of Active: 0, Finished: 1, Finalized: 2, Skipped: 3. Example: 0.
hostname	string|null	The name of the node which processes the job. Example: connect.
cluster	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string Local. Gives the name of the cluster when run external to the Connect host. Example: Kubernetes.
image	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string Local. References the name of the target image when content runs in a clustered environment such as Kubernetes. Example: someorg/image:jammy.
run_as	string|null	The UNIX user that executed this job. Example: rstudio-connect.
skip_reason	string|null	The reason why this job was skipped. Only present for jobs with a skipped status (e.g., when a duplicate job was already queued). Example: duplicate job already queued.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get job

GET /v1/content/{guid}/jobs/{key}

Get a job for a given piece of content by key. This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Responses

200

200: Successful response.

A job record representing a content execution.

Name	Type	Description
id	string	The job identifier. Example: 54.
ppid	string|null	The job’s parent process identifier. Example: 20253.
pid	string	The job’s process identifier. Example: 20253.
key	string	The job’s unique key identifier. Example: tHawGvHZTosJA2Dx.
remote_id	string|null	The job’s identifier for off-host execution configurations. Example: S3ViZXJuZXRlczpyZW5kZXItci1tYXJrZG93bi1zaXRlLWtnODJo.
app_id	string	This field is deprecated and has been renamed to content_id. Example: 54.
content_id	string	The identifier for this job’s parent content. Example: 54.
content_guid	string	The unique identifier for this job’s content. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
variant_id	string	The identifier of the variant owning this job. Example: 54.
variant_key	string	The key of the variant owning this job. May be empty if the variant is no longer available. Example: HidI2Kwq.
bundle_id	string	The identifier of a content bundle linked to this job. Example: 54.
start_time	string (date-time)	The timestamp (RFC3339) indicating when this job started. Example: 2006-01-02T15:04:05-07:00.
end_time	string (date-time)|null	The timestamp (RFC3339) indicating when this job finished. Example: 2006-01-02T15:04:05-07:00.
last_heartbeat_time	string (date-time)|null	The timestamp (RFC3339) indicating the last time this job was observed to be running. Example: 2006-01-02T15:04:05-07:00.
queued_time	string (date-time)|null	The timestamp (RFC3339) indicating when this job was added to the queue to be processed. Only scheduled reports will present a value for this field. Example: 2006-01-02T15:04:05-07:00.
queue_name	string|null	The name of the queue which processes the job. Only scheduled reports will present a value for this field. Example: default.
tag	string	A tag to identify the nature of the job. It can be one of unknown, build_report, build_site, build_jupyter, packrat_restore, python_restore, configure_report, run_app, run_api, run_tensorflow, run_python_api, run_dash_app, run_streamlit, run_bokeh_app, run_panel_app, run_fastapi_app, run_gradio_app, run_pyshiny_app, render_shiny, run_voila_app, testing, git, val_py_ext_pkg, val_r_ext_pkg, val_r_install. Example: build_report.
exit_code	integer|null	The job’s exit code. Present only when job is finished. Example: 0.
error	string|null	The error message if the job failed due to an unexpected server error.
status	integer	The current status of the job. It can be one of Active: 0, Finished: 1, Finalized: 2, Skipped: 3. Example: 0.
hostname	string|null	The name of the node which processes the job. Example: connect.
cluster	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string Local. Gives the name of the cluster when run external to the Connect host. Example: Kubernetes.
image	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string Local. References the name of the target image when content runs in a clustered environment such as Kubernetes. Example: someorg/image:jammy.
run_as	string|null	The UNIX user that executed this job. Example: rstudio-connect.
skip_reason	string|null	The reason why this job was skipped. Only present for jobs with a skipped status (e.g., when a duplicate job was already queued). Example: duplicate job already queued.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Register job kill order

DELETE /v1/content/{guid}/jobs/{key}

Request to register an order to kill a specific job. This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Responses

200

200: Successful response.

The result of registering an order to kill a job.

Name	Type	Description
guid	string	The unique identifier for the registered kill order. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
app_id	integer	This field is deprecated and has been renamed to content_id. Example: 54.
app_guid	string	This field is deprecated and has been renamed to content_guid. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
content_id	string	The identifier for this job’s parent content. Example: 54.
content_guid	string	The unique identifier for this job’s content. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
job_id	integer	The job’s id Example: 54.
job_key	string	The job’s unique key identifier. Example: tHawGvHZTosJA2Dx.
result	string	A short message describing the end result. Example: Order to kill job registered.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Download job log file

GET /v1/content/{guid}/jobs/{key}/download

Download a content job log file. This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Path parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Query parameters

Name	Type	Description
filename	string	false “The name of the file to retrieve”

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get job error

GET /v1/content/{guid}/jobs/{key}/error

Get the primary error for a job (if one exists). This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Responses

200

200: Successful response.

The primary error of a job.

Name	Type	Description
code	string	The error code.
summary	string	Summary of the error.
help_url	string	A help URL with further information about the error.

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get job log

GET /v1/content/{guid}/jobs/{key}/log

Get the log output for a given job. This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Path parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Query parameters

Name	Type	Description
maxLogLines	integer	false “The maximum number of log lines to return”

Responses

200

200: Successful response.

Log entries for a job.

Name	Type	Description
entries	[object]	The list of log entries.
entries[].source	string	The source of the log entry. stdout or stderr. Example: stdout.
entries[].timestamp	string (date-time)|null	The timestamp (RFC3339) indicating when this log entry was recorded. Example: 2006-01-02T15:04:05-07:00.
entries[].data	string	The log entry content. Example: Running on host: connect.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get job metrics

GET /v1/content/{guid}/jobs/{key}/metrics

Get resource usage metrics collected for a specific job.

Returns JSON data containing CPU, memory, and connection metrics sampled during job execution. The metrics are only available when per-content metrics collection is enabled for the content item.

This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Path parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Query parameters

Name	Type	Description
from	string
to	string

Responses

200

200: Successful response.

Resource usage metrics collected for a job.

Name	Type	Description
content_guid	string	The unique identifier for the content item. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
job_key	string	The job’s unique key identifier. Example: tHawGvHZTosJA2Dx.
samples	[object]	Array of metric samples collected during job execution. May be empty if no metrics were collected.
samples[].timestamp	string (date-time)	The timestamp (RFC3339) when this sample was recorded. Example: 2006-01-02T15:04:05-07:00.
samples[].cpu_fraction	number	CPU usage as a fraction (0.0 to 1.0 per core). Example: 0.25.
samples[].memory_bytes	integer	Memory usage in bytes. Example: 104857600.
samples[].connections	integer|null	Number of active connections to the process. May be null if connection counting is not available. Example: 5.
samples[].process_id	integer	The process ID being monitored. Example: 12345.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Tail job log

GET /v1/content/{guid}/jobs/{key}/tail

Actively tail the log output for a given job. This action is permitted for content owners, users with collaborator rights, and administrators.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
key	string	Required.

Responses

200

200: Successful response.

A single log entry.

Name	Type	Description
source	string	The source of the log entry. stdout or stderr. Example: stdout.
timestamp	string (date-time)|null	The timestamp (RFC3339) indicating when this log entry was recorded. Example: 2006-01-02T15:04:05-07:00.
data	string	The log entry content. Example: Running on host: connect.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get aggregated job statistics for scheduled content

GET /v1/experimental/jobs/summary

Get aggregated job statistics for scheduled content.

Returns total counts of running, waiting, succeeded, and failed scheduled jobs, plus a time-series histogram of job outcomes bucketed by time.

This endpoint includes only scheduled jobs. On-demand executions (ad-hoc deployments, manual runs) are excluded. This provides statistics specifically for scheduled content execution.

Authorization:

• Administrators see statistics for all content system-wide
• Publishers see statistics only for content they own or collaborate on (editor role or higher)
• Viewers are denied access (403 Forbidden)

The time bucketing strategy automatically adjusts based on the time range:

• Range < 2 hours → 5-minute buckets
• Range < 12 hours → 30-minute buckets
• Range < 2 days → 1-hour buckets
• Range < 10 days → 6-hour buckets
• Range < 60 days → 1-day buckets
• Range < 180 days → 7-day buckets
• Range >= 180 days → 30-day buckets

If no time range is specified, statistics cover all jobs in the database.

Parameters

Name	Type	Description
from	string	false “Include only jobs with start_time at or after this timestamp (RFC3339)”
to	string	false “Include only jobs with start_time at or before this timestamp (RFC3339)”

Responses

200

200: Successful response.

Aggregated job statistics with totals and time-bucketed histogram for scheduled jobs only.

Name	Type	Description
totals	object	Aggregated total counts of scheduled jobs by status.
totals.waiting	integer	Number of scheduled jobs queued but not yet started. For time ranges in the past, this will be 0. Example: 3.
totals.running	integer	Number of currently executing scheduled jobs. For time ranges in the past, this will be 0. Example: 1.
totals.succeeded	integer	Number of scheduled jobs that completed successfully (exit code 0). Example: 287.
totals.failed	integer	Number of scheduled jobs that failed (non-zero exit code). Example: 5.
totals.skipped	integer	Number of scheduled jobs that were skipped. Note: skipped jobs are tracked from Connect version 2026.03.0 onward. Example: 2.
buckets	[object]	Time-series histogram of scheduled job outcomes. Each bucket represents a time interval with counts of succeeded and failed scheduled jobs. The bucket interval is automatically determined based on the query time range (5 minutes to 30 days).
buckets[].timestamp	string (date-time)	The start time of this bucket (RFC3339). Scheduled jobs with start_time in the interval [timestamp, timestamp+interval) are counted in this bucket. Example: 2026-01-26T00:00:00Z.
buckets[].failed	integer	Number of scheduled jobs in this bucket that failed. Example: 4.
buckets[].succeeded	integer	Number of scheduled jobs in this bucket that succeeded. Example: 100.
buckets[].skipped	integer	Number of scheduled jobs in this bucket that were skipped. Note: skipped jobs are tracked from Connect version 2026.03.0 onward. Example: 1.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

OAuth Integration Templates

List OAuth templates

GET /v1/oauth/templates

List OAuth templates available to Posit Connect. You must have administrator or publisher privileges to perform this action.

Responses

200

200: Successful response.

Array of objects:

OAuthTemplate holds the set of available fields that can be configured when creating or updating an OAuth integration in Posit Connect.

Name	Type	Description
id	string	The primary identifier for this OAuth template. Example: custom.
name	string	A human readable name for this OAuth template. Example: Custom Integration.
description	string	A human readable description for this OAuth template. Example: A Custom integration is used to create OAuth integrations of any type.
sections	[object]	The sections of the template are used to group fields and options when building the UI.
sections[].id	integer	The primary identifier of the template section.
sections[].order	integer	The order of this section relative to other sections within the OAuth template.
sections[].name	string	The name of this section.
sections[].description	string	The description of this section.
options	[object]	The options of the template are used to define the set of boolean and drop-down inputs that the user configures when creating an OAuth integration.
options[].name	string	The primary identifier of the template option. The name is used as the map key in the config property of the OAuth integration payload. The type in the config payload must correspond to the type property of the template option, either string or boolean. For example, given the following OAuthTemplateOptions: [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, { ... "name": "bool_option", "type": "bool", }] A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "bool_option": true } }
options[].description	string	A description of the template option.
options[].section	integer	A reference to the template section that should contain this option.
options[].order	integer	The order of this option within the template section relative to other options and fields within the section.
options[].label	string	The label to use for this option.
options[].visibility_expression	object	A Boolean expression tree that indicates if this option is visible.
options[].visibility_expression.name	string	The name of a config field being compared. Name is only set on leaf nodes in the expression tree. Example: auth_mode.
options[].visibility_expression.value	object	The value which a config field is compared against. Value is only set on leaf nodes in the expression tree. Example: Public.
options[].visibility_expression.operator	string	A boolean operator which executes against the provided list of operands. Operator is only set on non-leaf nodes in the expression tree. Example: and.
options[].visibility_expression.operands	[unknown]	A list of recursively-defined expression tree nodes which are executed on by a boolean operator. Operands is only set on non-leaf nodes in the expression tree.
options[].type	string	The type of this option. A bool indicates that this option is a true/false input. A select indicates that this option is a dropdown input.
options[].values	[string]	A list of possible values when type = select.
options[].default	object	The default value of this option. The default value is either a boolean when type = bool, or a string when type = select. When type = select, the default value must also be contained in the values list. Example: Public.
fields	[object]	The fields of the template are used to define the set of text inputs that the user configures when creating an OAuth integration.
fields[].name	string	The primary identifier of the field. The name is used as the map kay in the config property of the OAuth integration payload. The type in the config payload must be a string. For example, given the following OAuthTemplateField: { ... "name": "client_id" } A valid OAuthIntegration config would be: { ... "config": { "client_id": "my-oauth-app-client-id" } }
fields[].description	string	A description of the template field.
fields[].section	integer	A reference to the template section that should contain this field.
fields[].order	integer	The order of this field within the template section relative to other options and fields within the section.
fields[].label	string	The label to use for this field.
fields[].visibility_expression	object	A Boolean expression tree that indicates if this field is visible.
fields[].visibility_expression.name	string	The name of a config field being compared. Name is only set on leaf nodes in the expression tree. Example: auth_mode.
fields[].visibility_expression.value	object	The value which a config field is compared against. Value is only set on leaf nodes in the expression tree. Example: Public.
fields[].visibility_expression.operator	string	A boolean operator which executes against the provided list of operands. Operator is only set on non-leaf nodes in the expression tree. Example: and.
fields[].visibility_expression.operands	[unknown]	A list of recursively-defined expression tree nodes which are executed on by a boolean operator. Operands is only set on non-leaf nodes in the expression tree.
fields[].default	string	The default value of this template field.
fields[].validation	string	A regular expression used to determine whether the input is valid.
fields[].validation_description	string	A description of the value constraints for a given field.
fields[].secret	boolean	Indicates whether the field value is considered secret and should be hidden.
fields[].multiline	boolean	Indicates whether the field accepts multiline text input.
environment_variables	[string]	The names of environment variables associated with this OAuth template.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get OAuth template details

GET /v1/oauth/templates/{key}

Get information about a specific OAuth template. You must have administrator or publisher privileges to perform this action.

Parameters

Name	Type	Description
key	string	Required.

Responses

200

200: Successful response.

OAuthTemplate holds the set of available fields that can be configured when creating or updating an OAuth integration in Posit Connect.

Name	Type	Description
id	string	The primary identifier for this OAuth template. Example: custom.
name	string	A human readable name for this OAuth template. Example: Custom Integration.
description	string	A human readable description for this OAuth template. Example: A Custom integration is used to create OAuth integrations of any type.
sections	[object]	The sections of the template are used to group fields and options when building the UI.
sections[].id	integer	The primary identifier of the template section.
sections[].order	integer	The order of this section relative to other sections within the OAuth template.
sections[].name	string	The name of this section.
sections[].description	string	The description of this section.
options	[object]	The options of the template are used to define the set of boolean and drop-down inputs that the user configures when creating an OAuth integration.
options[].name	string	The primary identifier of the template option. The name is used as the map key in the config property of the OAuth integration payload. The type in the config payload must correspond to the type property of the template option, either string or boolean. For example, given the following OAuthTemplateOptions: [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, { ... "name": "bool_option", "type": "bool", }] A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "bool_option": true } }
options[].description	string	A description of the template option.
options[].section	integer	A reference to the template section that should contain this option.
options[].order	integer	The order of this option within the template section relative to other options and fields within the section.
options[].label	string	The label to use for this option.
options[].visibility_expression	object	A Boolean expression tree that indicates if this option is visible.
options[].visibility_expression.name	string	The name of a config field being compared. Name is only set on leaf nodes in the expression tree. Example: auth_mode.
options[].visibility_expression.value	object	The value which a config field is compared against. Value is only set on leaf nodes in the expression tree. Example: Public.
options[].visibility_expression.operator	string	A boolean operator which executes against the provided list of operands. Operator is only set on non-leaf nodes in the expression tree. Example: and.
options[].visibility_expression.operands	[unknown]	A list of recursively-defined expression tree nodes which are executed on by a boolean operator. Operands is only set on non-leaf nodes in the expression tree.
options[].type	string	The type of this option. A bool indicates that this option is a true/false input. A select indicates that this option is a dropdown input.
options[].values	[string]	A list of possible values when type = select.
options[].default	object	The default value of this option. The default value is either a boolean when type = bool, or a string when type = select. When type = select, the default value must also be contained in the values list. Example: Public.
fields	[object]	The fields of the template are used to define the set of text inputs that the user configures when creating an OAuth integration.
fields[].name	string	The primary identifier of the field. The name is used as the map kay in the config property of the OAuth integration payload. The type in the config payload must be a string. For example, given the following OAuthTemplateField: { ... "name": "client_id" } A valid OAuthIntegration config would be: { ... "config": { "client_id": "my-oauth-app-client-id" } }
fields[].description	string	A description of the template field.
fields[].section	integer	A reference to the template section that should contain this field.
fields[].order	integer	The order of this field within the template section relative to other options and fields within the section.
fields[].label	string	The label to use for this field.
fields[].visibility_expression	object	A Boolean expression tree that indicates if this field is visible.
fields[].visibility_expression.name	string	The name of a config field being compared. Name is only set on leaf nodes in the expression tree. Example: auth_mode.
fields[].visibility_expression.value	object	The value which a config field is compared against. Value is only set on leaf nodes in the expression tree. Example: Public.
fields[].visibility_expression.operator	string	A boolean operator which executes against the provided list of operands. Operator is only set on non-leaf nodes in the expression tree. Example: and.
fields[].visibility_expression.operands	[unknown]	A list of recursively-defined expression tree nodes which are executed on by a boolean operator. Operands is only set on non-leaf nodes in the expression tree.
fields[].default	string	The default value of this template field.
fields[].validation	string	A regular expression used to determine whether the input is valid.
fields[].validation_description	string	A description of the value constraints for a given field.
fields[].secret	boolean	Indicates whether the field value is considered secret and should be hidden.
fields[].multiline	boolean	Indicates whether the field accepts multiline text input.
environment_variables	[string]	The names of environment variables associated with this OAuth template.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

OAuth Integrations

List OAuth integrations

GET /v1/oauth/integrations

List all OAuth integrations available to Posit Connect. You must have administrator or publisher privileges to perform this action.

Responses

200

200: Successful response.

Array of objects:

OAuthIntegration represents a custom OAuth integration available in Posit Connect.

Name	Type	Description
id	string	The internal numeric identifier of this OAuth integration. Example: 123.
guid	string (uuid)	The unique identifier of this OAuth integration which is used in REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was last updated. Example: 2006-01-02T15:04:05-07:00.
name	string|null	A descriptive name to identify each OAuth integration.
description	string|null	A brief text to describe each OAuth integration. Example: Integration with external system.
template	string|null	The template to use to configure this OAuth integration. See List OAuth templates for more information. Example: custom.
auth_type	string|null	The authentication type indicates which OAuth flow is used by this integration. The “Viewer” authentication type corresponds to the Authorization Code flow. The “Service Account” authentication type corresponds to the Client Credentials flow. Example: Viewer.
config	object	The OAuth integration configuration based on the template. See List OAuth templates for more information on available fields for each template. The configuration combines elements from both options and fields from a given template. For example, given the following template section: ... "options": [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, ... }], "fields": [{ ... "name": "client_id", "label": "Client ID" }, ... }] ... A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "client_id": "1b9b9733-43f5-4848-a894-f753f2fbaf41", ... } }
permissions	[object]	A list of permission records that define which users or groups have access to this OAuth integration.
permissions[].id	string	The internal identifier for this permission entry. Example: 101.
permissions[].guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
permissions[].integration_guid	string (uuid)	The identifier of the OAuth integration. Example: 62543474-5716-4423-92d1-b3a22163eb49.
permissions[].user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
permissions[].group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.
environment_variables	[string]	The names of the environment variables provisioned by this OAuth integration.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create an OAuth integration

POST /v1/oauth/integrations

Create a new OAuth integration. You must have administrator privileges to perform this action.

Request body

The fields that can be specified when creating an OAuth integration.

Name	Type	Description
name	string|null	A descriptive name to identify each OAuth integration. Example: Databricks Integration.
description	string|null	A brief text to describe each OAuth integration. Example: Integration with external system.
template	string	The template to use to configure this OAuth integration. See List OAuth templates for more information. Example: custom.
config	object	The OAuth integration configuration based on the template. See List OAuth templates for more information on available fields for each template. The configuration combines elements from both options and fields from a given template. For example, given the following OAuthTemplateOptions: ... "options": [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, ... }], "fields": [{ ... "name": "client_id", "label": "Client ID" }, ... }] ... A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "client_id": "1b9b9733-43f5-4848-a894-f753f2fbaf41", ... } }
permissions	[object]	An optional list of permissions to grant access to this OAuth integration. Each permission record specifies a user or group that can access the integration.
permissions[].user_guid	string (uuid)|null	The identifier of the user. Do not specify this field if you are adding a group. Example: 89a3c946-d73c-4781-8463-dd3cccff3fef.
permissions[].group_guid	string (uuid)|null	The identifier of the group. Do not specify this field if you are adding a user. Example: 998f3356-96f0-48a2-9655-94334615fa5b.

Responses

200

200: Successful response.

OAuthIntegration represents a custom OAuth integration available in Posit Connect.

Name	Type	Description
id	string	The internal numeric identifier of this OAuth integration. Example: 123.
guid	string (uuid)	The unique identifier of this OAuth integration which is used in REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was last updated. Example: 2006-01-02T15:04:05-07:00.
name	string|null	A descriptive name to identify each OAuth integration.
description	string|null	A brief text to describe each OAuth integration. Example: Integration with external system.
template	string|null	The template to use to configure this OAuth integration. See List OAuth templates for more information. Example: custom.
auth_type	string|null	The authentication type indicates which OAuth flow is used by this integration. The “Viewer” authentication type corresponds to the Authorization Code flow. The “Service Account” authentication type corresponds to the Client Credentials flow. Example: Viewer.
config	object	The OAuth integration configuration based on the template. See List OAuth templates for more information on available fields for each template. The configuration combines elements from both options and fields from a given template. For example, given the following template section: ... "options": [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, ... }], "fields": [{ ... "name": "client_id", "label": "Client ID" }, ... }] ... A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "client_id": "1b9b9733-43f5-4848-a894-f753f2fbaf41", ... } }
permissions	[object]	A list of permission records that define which users or groups have access to this OAuth integration.
permissions[].id	string	The internal identifier for this permission entry. Example: 101.
permissions[].guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
permissions[].integration_guid	string (uuid)	The identifier of the OAuth integration. Example: 62543474-5716-4423-92d1-b3a22163eb49.
permissions[].user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
permissions[].group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.
environment_variables	[string]	The names of the environment variables provisioned by this OAuth integration.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

402

402: The requested operation requires payment.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get OAuth integration details

GET /v1/oauth/integrations/{guid}

Get detailed information about a specific OAuth integration. You must have administrator or publisher privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

OAuthIntegration represents a custom OAuth integration available in Posit Connect.

Name	Type	Description
id	string	The internal numeric identifier of this OAuth integration. Example: 123.
guid	string (uuid)	The unique identifier of this OAuth integration which is used in REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was last updated. Example: 2006-01-02T15:04:05-07:00.
name	string|null	A descriptive name to identify each OAuth integration.
description	string|null	A brief text to describe each OAuth integration. Example: Integration with external system.
template	string|null	The template to use to configure this OAuth integration. See List OAuth templates for more information. Example: custom.
auth_type	string|null	The authentication type indicates which OAuth flow is used by this integration. The “Viewer” authentication type corresponds to the Authorization Code flow. The “Service Account” authentication type corresponds to the Client Credentials flow. Example: Viewer.
config	object	The OAuth integration configuration based on the template. See List OAuth templates for more information on available fields for each template. The configuration combines elements from both options and fields from a given template. For example, given the following template section: ... "options": [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, ... }], "fields": [{ ... "name": "client_id", "label": "Client ID" }, ... }] ... A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "client_id": "1b9b9733-43f5-4848-a894-f753f2fbaf41", ... } }
permissions	[object]	A list of permission records that define which users or groups have access to this OAuth integration.
permissions[].id	string	The internal identifier for this permission entry. Example: 101.
permissions[].guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
permissions[].integration_guid	string (uuid)	The identifier of the OAuth integration. Example: 62543474-5716-4423-92d1-b3a22163eb49.
permissions[].user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
permissions[].group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.
environment_variables	[string]	The names of the environment variables provisioned by this OAuth integration.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update an OAuth integration

PATCH /v1/oauth/integrations/{guid}

Update a specific OAuth integration. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when updating an OAuth integration.

Name	Type	Description
name	string|null	A descriptive name to identify each OAuth integration. Example: databricks.
description	string|null	A brief text to describe each OAuth integration. Example: Integration with external system.
config	object	The OAuth integration configuration based on the template. See List OAuth templates for more information on available fields for each template. The configuration combines elements from both options and fields from a given template. For example, given the following OAuthTemplateOptions: ... "options": [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, ... }], "fields": [{ ... "name": "client_id", "label": "Client ID" }, ... }] ... A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "client_id": "1b9b9733-43f5-4848-a894-f753f2fbaf41", ... } }
permissions	[object]	An optional list of permissions to grant access to this OAuth integration. Each permission record specifies a user or group that can access the integration. When provided, this replaces the existing permissions for the integration.
permissions[].user_guid	string (uuid)|null	The identifier of the user. Do not specify this field if you are adding a group. Example: 89a3c946-d73c-4781-8463-dd3cccff3fef.
permissions[].group_guid	string (uuid)|null	The identifier of the group. Do not specify this field if you are adding a user. Example: 998f3356-96f0-48a2-9655-94334615fa5b.

Responses

200

200: Successful response.

OAuthIntegration represents a custom OAuth integration available in Posit Connect.

Name	Type	Description
id	string	The internal numeric identifier of this OAuth integration. Example: 123.
guid	string (uuid)	The unique identifier of this OAuth integration which is used in REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was created. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth integration was last updated. Example: 2006-01-02T15:04:05-07:00.
name	string|null	A descriptive name to identify each OAuth integration.
description	string|null	A brief text to describe each OAuth integration. Example: Integration with external system.
template	string|null	The template to use to configure this OAuth integration. See List OAuth templates for more information. Example: custom.
auth_type	string|null	The authentication type indicates which OAuth flow is used by this integration. The “Viewer” authentication type corresponds to the Authorization Code flow. The “Service Account” authentication type corresponds to the Client Credentials flow. Example: Viewer.
config	object	The OAuth integration configuration based on the template. See List OAuth templates for more information on available fields for each template. The configuration combines elements from both options and fields from a given template. For example, given the following template section: ... "options": [{ ... "name": "auth_mode", "type": "select", "values": ["Confidential", "Public"] }, ... }], "fields": [{ ... "name": "client_id", "label": "Client ID" }, ... }] ... A valid OAuthIntegration config would be: { ... "config": { "auth_mode": "Public", "client_id": "1b9b9733-43f5-4848-a894-f753f2fbaf41", ... } }
permissions	[object]	A list of permission records that define which users or groups have access to this OAuth integration.
permissions[].id	string	The internal identifier for this permission entry. Example: 101.
permissions[].guid	string (uuid)	The identifier for this permission entry. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
permissions[].integration_guid	string (uuid)	The identifier of the OAuth integration. Example: 62543474-5716-4423-92d1-b3a22163eb49.
permissions[].user_guid	string (uuid)|null	The identifier of the user listed in the permission entry. This field will be null if a group is listed. Example: d73f7343-02e8-4c52-9208-598e28f8002e.
permissions[].group_guid	string (uuid)|null	The identifier of the group listed in the permission entry. This field will be null if a user is listed. Example: a46be0c8-ef75-4dce-b902-d8e56a6b8509.
environment_variables	[string]	The names of the environment variables provisioned by this OAuth integration.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

402

402: The requested operation requires payment.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete an OAuth integration

DELETE /v1/oauth/integrations/{guid}

Delete the OAuth integration associated with the provided guid. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List all associations for this OAuth integration.

GET /v1/oauth/integrations/{guid}/associations

List all associations for this OAuth integration. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

Represents an association between a content item and an OAuth integration.

Name	Type	Description
app_guid	string (uuid)	This field is deprecated and has been renamed to content_guid. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
content_guid	string (uuid)	The unique identifier of the content item. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
oauth_integration_guid	string (uuid)	The unique identifier of an existing OAuth integration. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
oauth_integration_name	string|null	A descriptive name that identifies the OAuth integration. Example: Databricks Integration.
oauth_integration_description	string|null	A brief text that describes the OAuth integration. Example: Integration with external system.
oauth_integration_template	string|null	The template used to configure this OAuth integration. Example: custom.
oauth_integration_auth_type	string|null	Indicates which OAuth flow is used by this integration. The “Viewer” authentication type corresponds to the Authorization Code flow. The “Service Account” authentication type corresponds to the Client Credentials flow. Example: Viewer.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this association was created. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Verify that an OAuth service account integration is configured correctly.

POST /v1/oauth/integrations/{guid}/verify

This endpoint simulates a content session token exchange with the OAuth integration to verify that the integration is configured correctly. No access token is returned. Verification is only available for OAuth integrations with the “Service Account” authentication type. If the integration is not a service account integration, a 400 status code will be returned. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

402

402: The requested operation requires payment.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Exchange Connect credentials for OAuth credentials

POST /v1/oauth/integrations/credentials

This endpoint facilitates an OAuth Token Exchange by exchanging a Connect-provided credential for OAuth credentials.

There are several types of OAuth token exchanges supported by this endpoint. It allows content owners to exchange the viewer’s Connect credentials for the viewer’s OAuth credentials, and it allows executing content to exchange its own Connect credentials for the OAuth credentials associated with a service account.

This endpoint can only be called from content that is running on Posit Connect because the Connect-provided credentials required by the endpoint are only available in that context. See the subject_token property for details.

In the case of a Viewer credential exchange, this endpoint requires that the content viewer first perform an OAuth login by visiting the login endpoint of the OAuth integration in their browser. The login endpoint is located at __oauth__/integrations/:guid/login.

Once the viewer has successfully initialized an OAuth session for the OAuth integration by visiting the login endpoint, the content can then exchange the viewer’s user-session-token for the viewer’s OAuth credentials.

OAuth credential refresh is handled automatically by Connect. Repeated requests to this endpoint will return the same OAuth credentials until they expire. When the OAuth credentials expire, the next request to this endpoint will return a refreshed set of OAuth credentials.

You must have administrator or publisher privileges to perform this action. Additionally, the requester must be owner of the content where the credential exchange request originated. Finally, the user whose OAuth credentials are being requested must have viewer permissions on the content.

In the case of a Service Account credential exchange, this endpoint will return a fresh OAuth access token to the requesting content item on every request. There is no login redirect or refresh token management. You must have administrator or publisher privileges to perform this action. The requester must be owner of the content where the credential exchange request originated.

Request body

Name	Type	Description
audience	string	Identifies the integration for which the OAuth credentials are being requested.
grant_type	string	Indicates that an OAuth Token Exchange is being requested. The value is always “urn:ietf:params:oauth:grant-type:token-exchange”.
requested_token_type	string	Identifies the type of token being requested.
subject_token	string	An opaque string that is used to identify the consumer of the OAuth access token.
subject_token_type	string	Identifies the type of subject_token in use.

Responses

200

200: Successful response.

Name	Type	Description
access_token	string|null	The user’s token which is accepted by the external resource. If issued_token_type is urn:ietf:params:aws:token-type:credentials, then this field will contain base64-encoded JSON containing temporary AWS credentials. https://datatracker.ietf.org/doc/html/rfc8693#section-2.2.1-2.2
issued_token_type	string|null	The type of token stored in the access_token field. https://datatracker.ietf.org/doc/html/rfc8693#section-2.2.1-2.4 Example: urn:ietf:params:oauth:token-type:access_token.
token_type	string|null	The method by which the access_token should be provided to the external resource. https://datatracker.ietf.org/doc/html/rfc8693#section-2.2.1-2.6 Example: Bearer.
expires_in	integer|null	The remaining time before the returned token expires, expressed in seconds. This value is only returned if expiry information is available for the token. For example, if an external OAuth service does not provide expiry information to Connect, this value can’t be returned in the response. Token expiration is calulated relative to the current UTC time, not local time. https://datatracker.ietf.org/doc/html/rfc8693#section-2.2.1-2.8 Example: 3600.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

402

402: The requested operation requires payment.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

OAuth Sessions

List OAuth sessions

GET /v1/oauth/sessions

List OAuth sessions available to Posit Connect associated with the current user. If you have administrator privileges you can request all available sessions.

Parameters

Name	Type	Description
all	boolean	false “When making a request with administrator privileges, include OAuth sessions for all users when set to true”

Responses

200

200: Successful response.

Array of objects:

OAuthSession represents an OAuth session for a given user associated to an OAuth integration.

Name	Type	Description
id	string	The internal numeric identifier of this OAuth session. Example: 123.
guid	string (uuid)	The unique identifier of this OAuth session which is used in REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
user_guid	string (uuid)|null	The unique identifier of the user that is associated with this OAuth session. Example: 21caced7-979e-4e83-ad11-01837528d9d9.
oauth_integration_guid	string (uuid)	The unique identifier of the OAuth integration that is associated with this OAuth session. Example: dd4a5e2-4714-401a-9404-4ca8eddcef2d.
has_refresh_token	boolean	Indicates whether this OAuth session has a refresh token.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth session was created. Example: 2020-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth session was last updated. Example: 2020-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get OAuth session details

GET /v1/oauth/sessions/{guid}

Get information about a specific OAuth session. If you have administrator privileges you can request details for any available session.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

OAuthSession represents an OAuth session for a given user associated to an OAuth integration.

Name	Type	Description
id	string	The internal numeric identifier of this OAuth session. Example: 123.
guid	string (uuid)	The unique identifier of this OAuth session which is used in REST API requests. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
user_guid	string (uuid)|null	The unique identifier of the user that is associated with this OAuth session. Example: 21caced7-979e-4e83-ad11-01837528d9d9.
oauth_integration_guid	string (uuid)	The unique identifier of the OAuth integration that is associated with this OAuth session. Example: dd4a5e2-4714-401a-9404-4ca8eddcef2d.
has_refresh_token	boolean	Indicates whether this OAuth session has a refresh token.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth session was created. Example: 2020-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when this OAuth session was last updated. Example: 2020-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete an OAuth session

DELETE /v1/oauth/sessions/{guid}

Delete the OAuth session associated with the provided guid. A user can delete their own sessions. Deleting sessions for other users requires administrator privileges.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Packages

Get package dependencies for all content

GET /v1/packages

Get the names and versions of all installed R and Python packages across all content items. Returned packages are sorted by language and then by package name. Content items with r_environment_management or python_environment_management set to false will not have their packages listed. This endpoint uses offset pagination. Requests can include query-string parameters for page_number and page_size to fetch different pages of results.

Parameters

Name	Type	Description
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
asc_order	boolean	Whether results are in ascending order.
name	string

Responses

200

200: Successful response.

An object containing a paginated list of packages.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The list of packages
results[].language	string	Language ecosystem the package belongs to
results[].language_version	string	Version of R or Python used by the content Example: 3.12.4.
results[].name	string	Package name Example: shiny.
results[].version	string	Package version Example: 1.0.3.
results[].hash	string|null	Package description hash for R packages Example: e4ac73dd20b2f6420742aac66e5d3e78.
results[].bundle_id	string	Identifier for the bundle that depends on this package Example: 449.
results[].app_id	string	This field is deprecated and has been renamed to content_id. Example: 145.
results[].app_guid	string (uuid)	This field is deprecated and has been renamed to content_guid. Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.
results[].content_id	string	Numeric identifier for the content that depends on this package Example: 145.
results[].content_guid	string (uuid)	The unique identifier of the content item that depends on this package Example: f4b3d7f6-7e1d-4f3b-8b9e-3f0f3f3f3f3f.

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Queue

List items in queue

GET /v1/queue

List all items currently in the job queue. This endpoint requires administrator access.

Parameters

Name	Type	Description
queue_names	string
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
asc_order	boolean	Whether results are in ascending order.

Responses

200

200: Successful response.

An object containing a paginated list of queue items.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The list of items in the current page
results[].id	string	The ID of the queue object Example: 135.
results[].name	string	Name of queue Example: job-finalizer.
results[].job_type	string	The type of job in the queue Example: ScheduledRender.
results[].created_time	string (date-time)	The time that the item was placed in the queue Example: 2006-01-02T15:04:05-07:00.
results[].updated_time	string (date-time)	The time that the enqueued item was updated Example: 2006-01-02T15:04:05-07:00.
results[].started_time	string (date-time)	The time that work started on the queued item Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete a queue item

DELETE /v1/queue/{id}

Deletes an item from the job queue. Only inactive items (not currently being processed) can be deleted.

Authenticated access from a user having an “administrator” role is required.

Parameters

Name	Type	Description
id	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Schedules

Get schedule history

GET /v1/content/{guid}/schedule/history

Get the schedule change history for a piece of content.

Returns the current schedule (if any) and a list of historical changes including when schedules were created, updated, or deleted.

Schedule data is returned in RFC 5545 (iCalendar) format.

A maximum of 100 history entries are returned, ordered by change time (most recent first).

This action is permitted for content owners, users with collaborator or editor rights, and administrators.

Parameters

Path parameters

Name	Type	Description
guid	string (uuid)	Required.

Query parameters

Name	Type	Description
variant	string

Responses

200

200: Successful response.

Name	Type	Description
results	[object]	An array of schedule history results, one per variant.
results[].variant_key	string	The unique key identifying this variant. Example: HidI2Kwq.
results[].current_schedule	object	The current active schedule for this variant, or null if no schedule exists.
results[].current_schedule.schedule	object	The schedule definition in RFC 5545 (iCalendar) format.
results[].current_schedule.schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
results[].current_schedule.schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
results[].current_schedule.schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
results[].current_schedule.next_run	string (date-time)|null	The next scheduled run time (RFC3339), or null if no future run is scheduled. Example: 2024-01-17T14:00:00Z.
results[].history	[object]	A list of schedule change history entries, ordered by change time (most recent first). Limited to the 100 most recent entries.
results[].history[].change_type	string	The type of change that was made to the schedule. Example: updated.
results[].history[].change_time	string (date-time)	The timestamp (RFC3339) when this change was made. Example: 2025-01-15T14:30:00Z.
results[].history[].user	object	The user who made this change, or null if the user has been deleted.
results[].history[].user.email	string	The user’s email. Example: jon.doe@example.com.
results[].history[].user.username	string	The user’s username. Example: jondoe.
results[].history[].user.first_name	string	The user’s first name. Example: Jon.
results[].history[].user.last_name	string	The user’s last name. Example: Doe.
results[].history[].user.user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
results[].history[].user.created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].history[].user.updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].history[].user.active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
results[].history[].user.confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
results[].history[].user.locked	boolean	Whether or not the user is locked. Example: false.
results[].history[].user.external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
results[].history[].user.guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
results[].history[].new_schedule	object	The schedule state after this change, or null if the schedule was deleted.
results[].history[].new_schedule.schedule	object	The schedule definition in RFC 5545 (iCalendar) format.
results[].history[].new_schedule.schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
results[].history[].new_schedule.schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
results[].history[].new_schedule.schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
results[].total_count	integer	The total number of history entries for this variant. This may be larger than the number of entries in the history array, which is limited to 100 entries. Example: 3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Server Information

Get Node.js Information

GET /v1/server_settings/nodejs

This endpoint returns a list of metadata objects for each version of Node.js that is available for executing content. This endpoint requires authentication and is only available to publisher and administrator roles.

Responses

200

200: Successful response.

This defines the top-level object that describes the data returned by the server. It contains information about each installation of Node.js that is known.

Name	Type	Description
installations	[object]	The array of information about Posit Connect’s Node.js installations.
installations[].version	string	The version number of this Node.js installation. Example: 22.11.0.
installations[].cluster_name	string	The cluster that contains this Node.js installation. A value of Local indicates that the Node.js installation is local to the Posit Connect server. Example: Kubernetes.
installations[].image_name	string	The image that contains this Node.js installation. A value of Local indicates that the Node.js installation is local to the Posit Connect server. Example: Local.
enabled	boolean	A true value is returned only when Node.js support is enabled in Connect and Node.js content is permitted by the product license (Advanced tier or Evaluation). It will be false in all other cases.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get public settings

GET /v1/server_settings/public

This endpoint returns the minimal server settings needed to render unauthenticated views in the Connect dashboard.

The returned settings include: - Authentication provider information (name, notice, timing) - Self-registration availability - System display name for branding - Username validation rules for registration

Security Note: This endpoint is public (no authentication required) and deliberately exposes minimal server settings to unauthenticated users.

Responses

200

200: Successful response.

Minimal server settings required for rendering the login page and related unauthenticated pages (e.g., password reset, registration). This is a public endpoint that provides only the information needed for unauthenticated users to authenticate.

Name	Type	Description
authentication	object	Authentication provider configuration.
self_registration	boolean	Whether users can self-register for an account. This is only true when password authentication is enabled and self-registration is configured, or when no users exist yet (allowing the first user to register). Example: false.
system_display_name	string	The display name for the server, used for branding in the UI. Example: Posit Connect.
public_warning	string	Optional warning message to display on public pages like the welcome and login pages. Can contain HTML. Example: ``.
customized_landing	boolean	Whether a custom landing page is configured to replace the default welcome page. Example: false.
mail_configured	boolean	Whether email is configured on the server. This determines whether features like password reset via email are available. Example: true.
prohibited_usernames	[string]	List of usernames that are not allowed for new user registration. These are reserved system names. Example: ["connect","apps","users","groups"].
username_validator	string	The username validation mode. Either “default” (strict validation with length and character requirements) or “permissive” (minimal validation, typically used with external authentication providers). Example: default.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get Python Information

GET /v1/server_settings/python

This endpoint returns a list of metadata objects for each version of Python that is available for executing content. This endpoint requires authentication and is only available to publisher and administrator roles.

Responses

200

200: Successful response.

This defines the top-level object that describes the data returned by the server. It contains information about each installation of Python that is known.

Name	Type	Description
installations	[object]	The array of information about Posit Connect’s Python installations.
installations[].version	string	The version number of this Python installation. Example: 3.10.6.
installations[].cluster_name	string	The cluster that contains this Python installation. A value of Local indicates that the Python installation is local to the Posit Connect server. Example: Kubernetes.
installations[].image_name	string	The image that contains this Python installation. A value of Local indicates that the Python installation is local to the Posit Connect server. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
api_enabled	boolean	A true value is returned only when Python support is enabled in Connect and API hosting is permitted by the product license. It will be false in all other cases.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get Quarto Information

GET /v1/server_settings/quarto

This endpoint returns a list of metadata objects for each version of Quarto that is available for executing content. This endpoint requires authentication and is only available to publisher and administrator roles.

Responses

200

200: Successful response.

This defines the top-level object that describes the data returned by the server. It contains information about each installation of Quarto that is known.

Name	Type	Description
installations	[object]	The array of information about Posit Connect’s Quarto installations.
installations[].version	string	The version number of this Quarto installation. Example: 1.0.27.
installations[].cluster_name	string	The cluster that contains this Quarto installation. A value of Local indicates that the Quarto installation is local to the Posit Connect server. Example: Kubernetes.
installations[].image_name	string	The image that contains this Quarto installation. A value of Local indicates that the Quarto installation is local to the Posit Connect server. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get R Information

GET /v1/server_settings/r

This endpoint returns a list of metadata objects for each version of R that is available for executing content. This endpoint requires authentication and is only available to publisher and administrator roles.

Responses

200

200: Successful response.

This defines the top-level object that describes the data returned by the server. It contains information about each installation of R that is known.

Name	Type	Description
installations	[object]	The array of information about Posit Connect’s R installations.
installations[].version	string	The version number of this R installation. Example: 3.4.4.
installations[].cluster_name	string	The cluster that contains this R installation. A value of Local indicates that the R installation is local to the Posit Connect server. Example: Kubernetes.
installations[].image_name	string	The image that contains this R installation. A value of Local indicates that the R installation is local to the Posit Connect server. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get TensorFlow Information

GET /v1/server_settings/tensorflow

This endpoint returns a list of metadata objects for each version of TensorFlow that is available for executing content. This endpoint requires authentication and is only available to publisher and administrator roles.

Responses

200

200: Successful response.

This defines the top-level object that describes the data returned by the server. It contains information about each installation of TensorFlow that is known.

Name	Type	Description
installations	[object]	The array of information about Posit Connect’s TensorFlow installations.
installations[].version	string	The version number of this TensorFlow installation. Example: 1.0.27.
installations[].cluster_name	string	The cluster that contains this TensorFlow installation. A value of Local indicates that the TensorFlow installation is local to the Posit Connect server. Example: Kubernetes.
installations[].image_name	string	The image that contains this TensorFlow installation. A value of Local indicates that the TensorFlow installation is local to the Posit Connect server. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List Time Zones

GET /v1/timezones

Returns the set of names and offsets for all time zones known by the server.

Responses

200

200: Successful response.

Array of objects:

One time zone entry with name and offset.

Name	Type	Description
timezone	string	The time zone name. Example: America/New_York.
offset	string	Time zone offset. Example: -04:00.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Service Tokens

List service tokens

GET /v1/system/service-tokens

List all service tokens. This endpoint is available only to administrators.

Responses

200

200: Successful response.

Array of objects:

Object containing service token details.

Name	Type	Description
guid	string (uuid)	The unique identifier for this service token. Example: f2aba5e9-1c6a-4f63-91c7-ec6ea5a2f8e7.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create a service token

POST /v1/system/service-tokens

Create a new service token with the specified scopes. This response includes the full token key. Subsequent requests do not include the key value. This endpoint is available only to administrators.

Request body

The input object for creating a service token.

Name	Type	Description
name	string	The name for this service token. Use the name to describe the purpose of the token. Names do not need to be unique. Example: NSS Integration.
scopes	[string]	The scopes to grant to this service token. At least one scope is required. Use the /v1/system/service-tokens/scopes endpoint to get available scopes. Example: ["nameservice:read"].

Responses

200

200: Successful response.

Object containing service token details.

Name	Type	Description
guid	string (uuid)	The unique identifier for this service token. Example: f2aba5e9-1c6a-4f63-91c7-ec6ea5a2f8e7.
name	string	The name for this service token. The name often describes the purpose of the token. Example: NSS Integration.
key	string	The secret key for this service token. The full key appears only when you create the token. Subsequent reads do not include the key. Example: abcdefghijklmnopqrstuvwxyz123456.
scopes	[string]	The scopes granted to this service token.
created_time	string (date-time)	Timestamp (in RFC 3339 format) indicating when you created the token. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)	Timestamp (in RFC 3339 format) indicating approximately when the token last authenticated. This value is updated when the token is used, but no more than once every 15 minutes. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete a service token

DELETE /v1/system/service-tokens/{guid}

Delete a service token. The token will immediately stop working for authentication. This endpoint is available only to administrators.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List available scopes

GET /v1/system/service-tokens/scopes

List all available scopes you can assign to service tokens. This endpoint is available only to administrators.

Responses

200

200: Successful response.

An object containing the available scopes for service tokens.

Name	Type	Description
scopes	[object]	The available scopes.
scopes[].name	string	The scope identifier. Example: nameservice:read.
scopes[].description	string	A human-readable description of what this scope grants. Example: Access NSS user and group data.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

System Checks

List system check runs

GET /v1/system/checks

List all system check runs that have been requested. You must have administrator privileges to perform this action.

Responses

200

200: Successful response.

Array of objects:

The fields returned when listing system check runs or getting the status of a run.

Name	Type	Description
id	string	The unique identifier for this test run. Example: 2.
start_time	string (date-time)	The timestamp (RFC3339) of when this run was started. Example: 2006-01-02T15:04:05-07:00.
hostname	string	The hostname where this test was run. Example: connect.example.com.
status	string	The status of this test run, one of: requested, running, done, canceled. Enum: requested, running, done, canceled. Example: done.
passed	integer	The number of tests in this run that have passed. Example: 29.
failed	integer	The number of tests in this run that have failed. Example: 1.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Start a system check run

POST /v1/system/checks

Start a system check run. The tests run in the background, and you can poll for status using the returned run ID. You must have administrator privileges to perform this action.

Request body

The fields to provide when running system checks.

Name	Type	Description
hostname	string|null	The hostname where this test was run. Optional. Defaults to the host Example: connect.example.com.

Responses

200

200: Successful response.

The fields returned when listing system check runs or getting the status of a run.

Name	Type	Description
id	string	The unique identifier for this test run. Example: 2.
start_time	string (date-time)	The timestamp (RFC3339) of when this run was started. Example: 2006-01-02T15:04:05-07:00.
hostname	string	The hostname where this test was run. Example: connect.example.com.
status	string	The status of this test run, one of: requested, running, done, canceled. Enum: requested, running, done, canceled. Example: done.
passed	integer	The number of tests in this run that have passed. Example: 29.
failed	integer	The number of tests in this run that have failed. Example: 1.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get the status of a system check run

GET /v1/system/checks/{id}

Get the status of a system check run.

Parameters

Name	Type	Description
id	string	Required.

Responses

200

200: Successful response.

The fields returned when listing system check runs or getting the status of a run.

Name	Type	Description
id	string	The unique identifier for this test run. Example: 2.
start_time	string (date-time)	The timestamp (RFC3339) of when this run was started. Example: 2006-01-02T15:04:05-07:00.
hostname	string	The hostname where this test was run. Example: connect.example.com.
status	string	The status of this test run, one of: requested, running, done, canceled. Enum: requested, running, done, canceled. Example: done.
passed	integer	The number of tests in this run that have passed. Example: 29.
failed	integer	The number of tests in this run that have failed. Example: 1.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete a system check run

DELETE /v1/system/checks/{id}

Delete a system check run and the associated results.

Parameters

Name	Type	Description
id	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get the results of a system check run

GET /v1/system/checks/{id}/results

Get the results of a system check run.

Parameters

Name	Type	Description
id	string	Required.

Responses

200

200: Successful response.

Fields containing results of a specific system check run.

Name	Type	Description
run	object	The run that was requested.
run.id	string	The unique identifier for this test run. Example: 2.
run.start_time	string (date-time)	The timestamp (RFC3339) of when this run was started. Example: 2006-01-02T15:04:05-07:00.
run.hostname	string	The hostname where this test was run. Example: connect.example.com.
run.status	string	The status of this test run, one of: requested, running, done, canceled. Enum: requested, running, done, canceled. Example: done.
run.passed	integer	The number of tests in this run that have passed. Example: 29.
run.failed	integer	The number of tests in this run that have failed. Example: 1.
results	[object]	The results of the system check run.
results[].group	object	Information about the test group that was run.
results[].group.name	string	The name of this test. Example: environment.
results[].group.args	string	The arguments that will be passed to this test.
results[].test	object	Information about the test that was run.
results[].test.name	string	The name of this test. Example: environment.
results[].test.args	string	The arguments that will be passed to this test.
results[].passed	boolean	Boolean indicating whether the test passed. Example: true.
results[].output	string	The textual output produced while running the test.
results[].error	string	The error that occurred while running this test, or empty string if no error occurred.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

System Information

List runtime caches

GET /v1/system/caches/runtime

List all content runtime caches. These include packrat and Python environment caches. This information is available only to administrators.

Responses

200

200: Successful response.

An object containing an array of runtime caches.

Name	Type	Description
caches	[object]	The list of runtime caches.
caches[].language	string	The runtime language of the cache. Example: Python.
caches[].version	string	The language version of the cache. Example: 3.8.12.
caches[].image_name	string	The name of the cache’s execution environment. Example: Local.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete a runtime cache

DELETE /v1/system/caches/runtime

Delete a content runtime package cache by specifying language, version, and execution environment. This action is only available to administrators.

Request body

Fields that describe the runtime cache to delete.

Name	Type	Description
language	string	The language of the target cache; either “R” or “Python”. Example: R.
version	string	The version of the target cache. Example: 4.1.2.
image_name	string	The execution environment of the target cache; either “Local” or an image name or identifier. Example: Local.
dry_run	boolean	When true, check input but do not delete cache. Example: true.

Responses

200

200: Successful response.

The response from a cache deletion request.

Name	Type	Description
language	string	The runtime language of the target cache. Example: Python.
version	string	The language version of the target cache. Example: 3.8.12.
image_name	string	The name of the target cache’s execution environment. Example: Local.
task_id	string|null	The identifier for the created deployment task. Always null for dry-run requests. Example: M49MsuXt6XVzlRdL.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List Connect hosts

GET /v1/system/hosts

List registered hosts. The default response includes hosts that are no longer active. Use the active parameter to return only active hosts. A host is considered active if it has checked in in the last 60 seconds. You must have administrator privileges to perform this action.

Parameters

Name	Type	Description
active	boolean	false “Return only active hosts”

Responses

200

200: Successful response.

Array of objects:

The fields returned when listing Connect hosts.

Name	Type	Description
hostname	string	The hostname or node name configured for the host. Example: connect.example.com.
version	string	The version of Connect running on the host. Example: 2021.10.0.
last_seen	string (date-time)	The timestamp (RFC3339) of when this host last checked in. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List Kubernetes service accounts

GET /v1/system/offhost/service-accounts

Applicable to Connect instances configured for off-host execution. List the Kubernetes service accounts discovered when Connect started. This action is available to publishers and administrators.

Responses

200

200: Successful response.

Kubernetes service accounts discovered when Connect started.

Name	Type	Description
enabled	boolean	Whether or not Kubernetes service accounts can be specified individually by content item. Reflects the configuration set for Launcher.KubernetesContentServiceAccountSelection.
default	string|null	The default configured service account to execute content. Unless otherwise configured via Launcher.KubernetesDefaultServiceAccount in your Connect configuration, this is the Kubernetes namespace default service account, “default.”
accounts	[string]	Array of strings with the service account names.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Tags

List tags for content

GET /v1/content/{guid}/tags

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.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

Array of objects:

A tag used to organize content within Connect.

Name	Type	Description
id	string	The identifier for the tag. Example: 101.
name	string	The name of the tag. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Add tag to content

POST /v1/content/{guid}/tags

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.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that must be specified when adding a tag to a content item.

Name	Type	Description
tag_id	string	The unique identifier for the tag. Example: 101.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Remove tag from content

DELETE /v1/content/{guid}/tags/{id}

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.

Parameters

Name	Type	Description
guid	string (uuid)	Required.
id	string	Required.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List tags

GET /v1/tags

List of all tags.

Authenticated access from a user is required.

Parameters

Name	Type	Description
name	string
parent_id	string

Responses

200

200: Successful response.

Array of objects:

A tag used to organize content within Connect.

Name	Type	Description
id	string	The identifier for the tag. Example: 101.
name	string	The name of the tag. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create tag

POST /v1/tags

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.

Request body

The fields that can be specified when creating or updating a tag.

Name	Type	Description
name	string|null	The name of the tag. Tags under the same parent must have a unique name and cannot be longer than 255 characters. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag will be a top-level tag. Example: 101.

Responses

200

200: Successful response.

A tag used to organize content within Connect.

Name	Type	Description
id	string	The identifier for the tag. Example: 101.
name	string	The name of the tag. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get tag

GET /v1/tags/{id}

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.

Parameters

Name	Type	Description
id	string	Required.

Responses

200

200: Successful response.

A tag used to organize content within Connect.

Name	Type	Description
id	string	The identifier for the tag. Example: 101.
name	string	The name of the tag. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update tag

PATCH /v1/tags/{id}

Update an existing tag.

Authenticated access from a user having an “administrator” role is required.

Parameters

Name	Type	Description
id	string	Required.

Request body

The fields that can be specified when creating or updating a tag.

Name	Type	Description
name	string|null	The name of the tag. Tags under the same parent must have a unique name and cannot be longer than 255 characters. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag will be a top-level tag. Example: 101.

Responses

200

200: Successful response.

A tag used to organize content within Connect.

Name	Type	Description
id	string	The identifier for the tag. Example: 101.
name	string	The name of the tag. Example: financial-statements.
parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete tag

DELETE /v1/tags/{id}

Deletes a tag, including all descendants in its own tag hierarchy.

Authenticated access from a user having an “administrator” role is required.

Parameters

Name	Type	Description
id	string	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List content for tags

GET /v1/tags/{id}/content

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.

Parameters

Name	Type	Description
id	string	Required.

Responses

200

200: Successful response.

Array of objects:

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.

Name guid	Type string (uuid)	Description The unique identifier of this content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
name	string	A simple identifier. Allows alpha-numeric characters, periods ("."), hyphens ("-"), and underscores ("_"). Example: quarterly-analysis.
title	string|null	The title of this content. Example: Quarterly Analysis of Team Velocity.
description	string	A rich description of this content. Example: This report calculates per-team statistics ....
access_type	string	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.
locked	boolean	Whether or not the content is locked. Example: false.
locked_message	string	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.
connection_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
read_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 3600.
init_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 60.
idle_timeout	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 5.
max_processes	integer|null	Specifies the total number of concurrent processes allowed for a single interactive application per Posit Connect node. When null, the default Scheduler.MaxProcesses is used. Applies only to content types that are executed on demand. Example: 3.
min_processes	integer|null	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.
max_conns_per_process	integer|null	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 is used. Applies only to content types that are executed on demand. Example: 20.
load_factor	number|null	Controls how aggressively new processes are spawned. When null, the default Scheduler.LoadFactor is used. Applies only to content types that are executed on demand. Example: 0.5.
memory_request	integer|null	The minimum amount of RAM this content needs when executing or rendering, expressed in bytes. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.MemoryRequest is used. Example: 1073741824.
memory_limit	integer|null	The maximum amount of RAM this content will be allowed to consume when executing or rendering, expressed in bytes. If the process tries to use more memory than allowed, it will be terminated. When null, the default Scheduler.MemoryLimit is used. Example: 2147483648.
cpu_request	number|null	The minimum amount of compute power this content needs when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration to determine where the content should be run. When null, the default Scheduler.CPURequest is used. Example: 1.
cpu_limit	number|null	The maximum amount of compute power this content will be allowed to consume when executing or rendering, expressed in “CPU Units”, where 1.0 unit is equivalent to 1 physical or virtual core. Fractional values are allowed. This is used when running in an off-host execution configuration. If the process tries to use more CPU than allowed, it will be throttled. When null, the default Scheduler.CPULimit is used. Example: 1.5.
amd_gpu_limit	integer|null	The number of AMD GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.AMDGPULimit is used. This setting can not exceed Scheduler.MaxAMDGPULimit. Example: 1.
nvidia_gpu_limit	integer|null	The number of NVIDIA GPUs that will be allocated by Kubernetes to run this content. This is used when running in an off-host execution configuration. When null, the default Scheduler.NvidiaGPULimit is used. This setting can not exceed Scheduler.MaxNvidiaGPULimit. Example: 1.
service_account_name	string|null	The name of the Kubernetes service account that is used to run a particular piece of content. It must adhere to valid Kubernetes service account naming rules. Connect must be configured to run with Launcher.Enabled = true, Launcher.Kubernetes = true and Launcher.KubernetesContentServiceAccountSelection = true for this value to be applied. It will have precedence over the Launcher.KubernetesDefaultServiceAccount that may be set in the configuration for Connect. If this value is defined and Connect is configured with Launcher.KubernetesContentServiceAccountSelection = false an error will be returned. Only administrators and publishers can view this value. Only administrators can set or change this value. Example: rstudio-connect-content.
default_image_name	string|null	The default image that will be used when none is defined by the bundle’s manifest. A specific image may be selected by setting the environment.image field in the manifest. If no image is selected by the manifest file, then the default_image_name is used. If a target image is not defined by the manifest, and no default_image_name is configured, then Connect will select an image from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
default_environment_guid	string (uuid)|null	The default execution environment that will be used when none is defined by the bundle’s manifest. A specific execution environment may be selected by setting the environment.identifier field in the manifest. If no execution environment is selected by the manifest file, then default_environment_guid is used to select the execution environment. If a target execution environment is not defined by the manifest, and no default_environment_guid is configured, then Connect will select an execution environment from the list of configured execution environments. If either environment.identifier or environment.image is specified in the bundle’s manifest.json then the settings in the manifest are used and the content-level default settings will be ignored. This allows historical bundle activation to behave consistently even when the content-level default values may have changed. A null value is returned when the client does not have sufficient rights to see this information. Use the /v1/environments API endpoints to determine which environments are available for content execution. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this content was created. Example: 2006-01-02T15:04:05-07:00.
last_deployed_time	string (date-time)	The timestamp (RFC3339) indicating when this content last had a successful bundle deployment performed. Example: 2006-01-02T15:04:05-07:00.
bundle_id	string|null	The identifier for the active deployment bundle. Automatically assigned upon the successful deployment of that bundle. Example: 101.
app_mode	string	The runtime model for this content. Has a value of unknown before data is deployed to this item. Automatically assigned upon the first successful bundle deployment. Valid values are: api - R code defining a Plumber API. jupyter-static - A Jupyter Notebook. jupyter-voila A Voila interactive dashboard. python-api - Python code defining a WSGI API (such as Flask) python-bokeh - Python code defining a Bokeh application. python-panel - Python code defining a Panel application. python-dash - Python code defining a Dash application. python-fastapi - Python code defining an ASGI API (such as FastAPI) python-gradio - Python code defining a Gradio application. python-shiny - Python code defining a Shiny application. python-streamlit - Python code defining a Streamlit application. quarto-shiny - A Quarto document with a Shiny runtime. quarto-static - A Quarto document or site. rmd-shiny - An R Markdown document with a Shiny runtime. rmd-static - An R Markdown document or site. shiny - R code defining a Shiny application. static - Content deployed without source; often HTML and plots. tensorflow-saved-model - A TensorFlow Model API. unknown - No known runtime model. Example: shiny.
content_category	string	Describes the specialization of the content runtime model. | Automatically assigned upon the first successful bundle deployment. | | The content_category field refines the type of content specified by | app_mode. It is empty by default. The rsconnect R package may assign | a value when analyzing your content and building its manifest and | bundle. Plots (images created in the RStudio IDE and presented in the | “Plots” pane) have an app_mode of static and receive a | content_category of plot to distinguish them from other HTML | documents. Pinned static data sets have an app_mode of static and a | content_category of pin. Multi-document R Markdown sites have an | app_mode of rmd-static and a content_category of site. | API content types (such as FastAPI, Flask, or Plumber) that serve as | MCP servers have a content_category of mcp. The mcp category is | auto-detected on first deploy but can also be set or cleared via | PATCH /v1/content/{guid}. | | Example: site. |
parameterized	boolean	True when R Markdown rendered content allows parameter configuration. Automatically assigned upon the first successful bundle deployment. Applies only to content with an app_mode of rmd-static. Example: false.
environment_guid	string (uuid)|null	The guid of the execution environment used to run this content. Content running locally on the same server as Connect will have either a null value. A null value is returned when the client does not have sufficient rights to see this information. Example: 36538b83-ea6d-4839-ae8e-53c52ac5f0bf.
cluster_name	string|null	The location where this content runs. Content running on the same server as Connect will have either a null value or the string “Local”. Gives the name of the cluster when run external to the Connect host. A null value is returned when the client does not have sufficient rights to see this information. Example: Local.
image_name	string|null	The name of the container image used to run this content in containerized environments such as Kubernetes. Content running locally on the same server as Connect will have either a null value or the string “Local”. A null value is returned when the client does not have sufficient rights to see this information. Example: rstudio/content-base:r4.1.3-py3.10.11-jammy.
r_version	string|null	The of R interpreter associated with this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.5.1.
py_version	string|null	The version of Python associated with this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 3.8.2.
quarto_version	string|null	The version of Quarto associated with this content. A null represents that Quarto is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 0.2.22.
node_version	string|null	The version of Node.js associated with this content. A null represents that Node.js is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: 22.11.0.
r_environment_management	boolean|null	Indicates whether or not Connect is managing an R environment and has installed the required packages for this content. A null value represents that R is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_r_environment_management	boolean|null	Indicates whether or not Connect should create and manage an R environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
py_environment_management	boolean|null	Indicates whether or not Connect is managing a Python environment and has installed the required packages for this content. A null value represents that Python is not used by this content, that the content has not been prepared for execution, or that the client does not have sufficient rights to see this information. Automatically assigned upon the successful deployment of a bundle. Example: true.
default_py_environment_management	boolean|null	Indicates whether or not Connect should create and manage a Python environment (installing required packages) for this content. When null, Connect makes this determination based on the server configuration. A null value is also returned when the client does not have sufficient rights to see this information. This value is ignored if the server setting Applications.DefaultEnvironmentManagementSelection is disabled. Example: true.
run_as	string|null	The UNIX user that executes this content. When null, the default Applications.RunAs is used. Applies only to executable content types - not static. Only administrators can change this value. If Applications.RunAsEnabled = false, this value will be ignored when executing content. Example: rstudio-connect.
run_as_current_user	boolean	Indicates that Connect should run processes for this content item under the Unix account of the user who visits it. Content accessed anonymously will continue to run as the specified run_as user. Connect must be configured to use PAM authentication with the server settings Applications.RunAsCurrentUser = true and PAM.ForwardPassword = true. This setting has no effect for other authentication types. This setting only applies to application content types (Shiny, Dash, Streamlit, Bokeh, and Panel). Only administrators can change this value. Example: false.
metrics_collection_enabled	boolean|null	Controls whether per-job resource metrics (CPU, memory, connections) | are collected for this content item. | | When null, the content item inherits the server-wide default from | Applications.MetricsCollectionEnabled. Explicit true or false | values override the server default. | | Metrics can be retrieved via the | GET /v1/content/{guid}/jobs/{key}/metrics endpoint. | Example: true. |
notify_on_share	boolean|null	Controls whether email notifications are sent by default when users or groups are added as collaborators or viewers. When null, the content item inherits the server-wide default from Applications.NotifyOnShare. Explicit true or false values override the server default. Example: true.
trace_collection_enabled	boolean	Whether per-job OpenTelemetry traces are collected for this content item. Traces are collected only when both this field and the server setting Applications.AllowTraceCollection are true. Example: false.
owner_guid	string (uuid)	The unique identifier of the user who created this content item. Automatically assigned when the content is created. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
content_url	string	The URL associated with this content. Computed from the associated GUID for this content. Example: https://posit-connect.company.com/content/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
dashboard_url	string	The URL within the Connect dashboard where this content can be configured. Computed from the GUID for this content. Example: https://posit-connect.company.com/connect/#/apps/9d8e7f3e-92e8-4a08-b0ff-196319cc56ae.
vanity_url	string	The vanity URL associated with this content item. Included in responses when the vanity URL is set and include=vanity_url is provided. Example: https://posit-connect.company.com/my-content/.
app_role	string	The relationship of the accessing user to this content. A value of owner is returned for the content owner. editor indicates a collaborator. The viewer value is given to users who are permitted to view the content. A none role is returned for administrators who cannot view the content but are permitted to view its configuration. Computed at the time of the request. Example: owner.
bookmarked	boolean|null	Indicates whether the requesting user has bookmarked this content item. Included in responses when include=bookmarked is provided. Example: true.
schedules	[object]	Schedules associated with this content item. Included in responses when include=schedule is provided.
schedules[].type	string	The schedule type. Example: rrule.
schedules[].schedule	object	The recurrence rule in RFC5545 format.
schedules[].schedule.dtstart	string	The DTSTART component specifying when the schedule begins, including timezone information. Example: DTSTART;TZID=America/New_York:20240115T090000.
schedules[].schedule.rrules	[string]	An array of RRULE components defining the recurrence pattern. Example: ["RRULE:FREQ=DAILY;INTERVAL=2"].
schedules[].schedule.until	string	The UNTIL component specifying when the schedule ends, if applicable. Example: UNTIL=20240215T090000Z.
schedules[].next_run	string (date-time)|null	The next scheduled run time. Null if no future runs are scheduled.
schedules[].email	boolean	Whether email notifications are enabled for this schedule. Example: false.
schedules[].timezone	string	The timezone for this schedule. Example: America/New_York.
schedules[].start_time	string (date-time)|null	The start time of the schedule window.
schedules[].end_time	string (date-time)|null	The end time of the schedule window. Null if the schedule runs indefinitely.
schedules[].last_run	object	Information about the last scheduled run.
schedules[].last_run.job_key	string	The unique key of the job. Example: abc123xyz.
schedules[].last_run.status	string	The status of the last run. Example: success.
schedules[].last_run.scheduled_time	string (date-time)|null	The scheduled time of the run.
schedules[].last_run.queued_time	string (date-time)|null	The time the run was queued.
schedules[].last_run.start_time	string (date-time)	The time the run started.
schedules[].last_run.end_time	string (date-time)|null	The time the run ended. Null if still running.
schedules[].last_run.run_duration_ms	integer|null	The duration of the run in milliseconds. Null if still running. Example: 5000.
schedules[].last_run.exit_code	integer|null	The exit code of the job. Null if still running. Example: 0.
schedules[].variant	object	Variant information embedded in a schedule.
schedules[].variant.key	string	The variant key. Example: default.
schedules[].variant.name	string	The variant name. Example: Default Variant.
schedules[].variant.is_default	boolean	Whether this is the default variant. Example: true.
id	string	The internal numeric identifier of this content item. Example: 314.
tags	[object]	Tags associated with this content item. Included in responses when include=tags is provided. Returns an empty array when content has no tags.
tags[].id	string	The identifier for the tag. Example: 101.
tags[].name	string	The name of the tag. Example: financial-statements.
tags[].parent_id	string|null	The identifier for the parent tag. If there is no parent_id, the tag is a top-level tag. Example: 102.
tags[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was created. Example: 2006-01-02T15:04:05Z.
tags[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when the tag was updated. Example: 2006-01-02T15:04:05Z.
owner	object	Basic details about the owner of this content item. Included in responses when include=owner is provided.
owner.guid	string (uuid)	The owner’s unique identifier. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
owner.username	string|null	The owner’s username. Example: jondoe.
owner.first_name	string|null	The owner’s first name. Example: Jon.
owner.last_name	string|null	The owner’s last name. Example: Doe.
public_content_status	string|null	Validation status of public interactive content. When validation is required by licensing, this will be one of “ok”, “warning”, or “restricted”. If licensing does not require validation, it will be “unrestricted”; if licensing does not allow public interactive content, it will be “unlicensed”. If the app has not been made public, but public content is permitted, it will be “none”. Example: unrestricted.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Tasks

Get task details

GET /v1/tasks/{id}

Returns the current state of a task and any output lines past the requested initial position (first).

When wait is non-zero, will wait up to that number of seconds for the task to complete before responding. The current state of the task is returned once the task completes or wait seconds elapse.

Incrementally receive task output by using the last response field value as the first value in a subsequent query.

Use wait and first together to incrementally fetch generated output.

Here is a URL that allows up to 5 seconds before returning all available output:

/v1/tasks/CmsfmnfDDyRUrsAc?wait=5&first=0

Let’s assume that request has a JSON response with the last field having a value of 23. Here is a URL that requests output past that point, again allowing up to 5 seconds:

/v1/tasks/CmsfmnfDDyRUrsAc?wait=5&first=23

Continue with this pattern until the finished field in the JSON response is true.

Note: In high-availability clustered deployments of Connect, the task request must be serviced by the node that is executing the task. This is done by ensuring that the cookies returned from the deployment operation are included in subsequent requests, so that the load balancer can appropriately direct the request. In a single-node configuration, the cookie can be omitted.

Parameters

Path parameters

Name	Type	Description
id	string	Required.

Query parameters

Name	Type	Description
first	integer
wait	integer

Responses

200

200: Successful response.

The task tracks the output and status of some operation being performed by Posit Connect. It is most commonly used to contain details about the progress of a deployment operation.

Name	Type	Description
id	string	The identifier for this task. Example: jXhOhdm5OOSkGhJw.
output	[string]	An array containing lines of output produced by the task. The initial line of output is dictated by the first input parameter. The offset of the last output line is indicated by the last response field.
result	object|null	A value representing the result of the operation, if any. For deployment tasks, this value is null. Example: null.
finished	boolean	Indicates that a task has completed. Example: true.
code	integer	Numeric indication as to the cause of an error. Non-zero when an error has occurred. Example: 1.
error	string	Description of the error. An empty string when no error has occurred. Example: Unable to render: Rendering exited abnormally: exit status 1.
last	integer	The total number of output lines produced so far. Use as the value to first in the next request to only fetch output lines beyond what you have already received. Example: 2.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Users

Get current user details

GET /v1/user

Get detailed information on the requesting user.

Responses

200

200: Successful response.

A user object.

Name	Type	Description
email	string	The user’s email. Example: jon.doe@example.com.
username	string	The user’s username. Example: jondoe.
first_name	string	The user’s first name. Example: Jon.
last_name	string	The user’s last name. Example: Doe.
user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
locked	boolean	Whether or not the user is locked. Example: false.
external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List or search for user details

GET /v1/users

This endpoint lists local users. When called with a prefix parameter, it searches for local users matching the prefix.

By default, results are sorted by first name, then last name, then username, then email. Use the sort parameter to sort by a different field. prefix searches are first sorted based on similarity to the prefix and then by the active sort field. The prefix can also be an exact match for the user’s DN (for LDAP) or the auth provider’s unique ID for the user, if any.

• The email field is not populated for non-admins when Server.HideEmailAddresses is enabled.
• The external_id field is only visible to administrators and to users viewing their own record.
• When the user making the request is a viewer and Authorization.ViewersCanOnlySeeThemselves is being used, the results contain only the given user.

This endpoint uses offset pagination. Requests can include query-string parameters for page_number and page_size to fetch different pages of results.

Note that searching by prefix will only return the first page of results; subsequent pages will be empty. Set page_size to its maximum (500) to retrieve the most results.

CSV export

Administrators can request the response as CSV by setting the Accept header to text/csv. The CSV export ignores pagination parameters and returns all matching users.

curl -H "Authorization: Key ${API_KEY}" \
     -H "Accept: text/csv" \
     "https://connect.example.com/__api__/v1/users"

Parameters

Name	Type	Description
prefix	string
page_number	integer	The page number to return.
page_size	integer	The number of items per page.
asc_order	boolean	Whether results are in ascending order.
page_size	integer
sort	string
prefix	string	Filter by a prefix string matched against username, first name, last name, provider key, and DN.
sort	string	Sort results by field. Defaults to first_name.
user_role	string	Filter by user role. | represents logical OR.
account_status	string	Filter by account status. | represents logical OR.

Responses

200

200: Successful response.

The users list with paging information.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The users list
results[].email	string	The user’s email. Example: jon.doe@example.com.
results[].username	string	The user’s username. Example: jondoe.
results[].first_name	string	The user’s first name. Example: Jon.
results[].last_name	string	The user’s last name. Example: Doe.
results[].user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
results[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
results[].confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
results[].locked	boolean	Whether or not the user is locked. Example: false.
results[].external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
results[].guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create a user from caller-supplied details (SAML, password, PAM, proxied, OAuth2 except with Google)

POST /v1/users

This endpoint creates the given user.

• This endpoint is used only for SAML, OAuth2 (non-Google), password, PAM, and proxied authentication. All other authentication providers should use the PUT /v1/users endpoint.
• Administrator access is required to create other users.

Initial User Creation Workflow

This endpoint requires authentication to create other users, which means that you need an API key for access. How do you get an API key if there are no users in Posit Connect?

• For password authentication, you can use this endpoint without an API key to create the first user. The first user will be an administrator.
• For SAML, OAuth2 (non-Google), PAM or proxied authentication, the first user can be created by logging into Posit Connect. The API cannot be used.

Once the first user is created, an API key can be used to access this endpoint and create subsequent users. The API Keys chapter of the Posit Connect User Guide explains how to create an API key.

All Authentication Providers

• When user_role is not specified, it will default to the role specified by the config setting Authorization.DefaultUserRole.

SAML, OAuth2 (non-Google), PAM and Proxied Authentication

• An API key must always be used. Users cannot use this endpoint to create their own account.
• Administrator access is always required to create accounts.
• external_id is required for SAML and OAuth2 (non-Google) authentication, and also for proxied authentication if the ProxyAuth.UniqueIdHeader config setting is used. It is not required for PAM, nor for proxied authentication without the ProxyAuth.UniqueIdHeader setting.

Password Authentication

• Users must confirm their account through an email. This feature is unique to password authentication.
• Administrator access is always required except for the first created user.

Request body

The fields that can be specified when creating a user from caller-supplied details.

Name	Type	Description
username	string	The user’s desired username. Example: jondoe.
first_name	string	The user’s first name. Example: Jon.
last_name	string	The user’s last name. Example: Doe.
email	string	The user’s email address. Example: jon.doe@example.com.
user_role	string|null	The user’s role. When null, the role is determined by the server default. Enum: administrator, publisher, viewer. Example: publisher.
user_must_set_password	boolean	When true, the created user will be asked to set the password on first login. Example: false.
password	string	The user’s initial password. Must meet minimum password requirements.
external_id	string	The unique identifier for this user from the authentication provider. Example: okta-12345-abcde.
unique_id	string	Deprecated: use external_id instead. Example: okta-12345-abcde.

Responses

200

200: Successful response.

A user object.

Name	Type	Description
email	string	The user’s email. Example: jon.doe@example.com.
username	string	The user’s username. Example: jondoe.
first_name	string	The user’s first name. Example: Jon.
last_name	string	The user’s last name. Example: Doe.
user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
locked	boolean	Whether or not the user is locked. Example: false.
external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Create a user using details from a remote authentication provider (LDAP, OAuth2 with Google)

PUT /v1/users

This endpoint creates the given user on the Posit Connect server.

• This endpoint is used only for LDAP and OAuth2 with Google authentication. All other authentication providers should use the POST /v1/users endpoint.
• Unlike the POST /v1/users endpoint, publisher or administrator access is required to access this endpoint.

User Creation Workflow on LDAP and OAuth2 with Google

This endpoint requires authentication, which means that you need an API key for access. How do you get an API key if there are no users in Posit Connect? The first user can be created by simply logging into Posit Connect. The Posit Connect Server API cannot be used to create the first user. Once logged in, you can create an API key.

For LDAP and OAuth2 with Google, the API lets you identify an existing user in the LDAP or OAuth2 with Google system and create a corresponding account on Posit Connect. This is a two-step process:

• Use the GET /v1/users/remote endpoint. This endpoint will return a list of potential matching accounts in LDAP or OAuth2 with Google. A user with no account on Posit Connect will lack a guid. Note the temp_ticket for the desired user account.
• Use this PUT endpoint with the temp_ticket to create a corresponding account on Posit Connect.

The Cookbook contains a recipe on Creating a User Using a Remote Authentication Provider (LDAP) which demonstrates this workflow using the Python and R SDKs.

LDAP and OAuth2 with Google Authentication

• The created user role will default to the role specified by the config setting Authorization.DefaultUserRole.

Request body

The fields that must be specified when creating a user from a remote authentication provider.

Name	Type	Description
temp_ticket	string	This value is for actions that require a temp_ticket, such as adding an LDAP or OAuth2 with Google user to the Connect server.

Responses

200

200: Successful response.

A user object.

Name	Type	Description
email	string	The user’s email. Example: jon.doe@example.com.
username	string	The user’s username. Example: jondoe.
first_name	string	The user’s first name. Example: Jon.
last_name	string	The user’s last name. Example: Doe.
user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
locked	boolean	Whether or not the user is locked. Example: false.
external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Get user details

GET /v1/users/{guid}

Get detailed information on a specific user.

The email field is not populated for non-admins when Server.HideEmailAddresses is enabled. The external_id field is only visible to administrators and to users viewing their own record.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

A user object.

Name	Type	Description
email	string	The user’s email. Example: jon.doe@example.com.
username	string	The user’s username. Example: jondoe.
first_name	string	The user’s first name. Example: Jon.
last_name	string	The user’s last name. Example: Doe.
user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
locked	boolean	Whether or not the user is locked. Example: false.
external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
guid	string (uuid)	The user’s GUID, or unique identifier, in UUID RFC4122 format Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Update a user

PUT /v1/users/{guid}

This endpoint updates a given user and returns the updated user properties. Note that it returns only the properties that can be modified by this endpoint.

If the authentication provider allows it:

• a user can change their own user properties.
• another user’s properties can be changed with administrator access.
• The configuration setting Authorization.UserInfoEditableBy controls whether or not non-admins can edit their own properties.

Password Authentication

• Emails are required.
• Changing an unconfirmed user’s email will cause the confirmation email to be resent to the new email.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when updating a user.

Name	Type	Description
email	string	The user’s email. Example: jon.doe@example.com.
username	string	The user’s username. Example: jondoe.
first_name	string	The user’s first name. Example: Jon.
last_name	string	The user’s last name. Example: Doe.
user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.

Responses

200

200: Successful response.

The editable user properties.

Name	Type	Description
email	string	The user’s email Example: jon.doe@example.com.
username	string	The user’s username Example: jondoe.
first_name	string	The user’s first name Example: Jon.
last_name	string	The user’s last name Example: Doe.
user_role	string	The user’s role Example: administrator.
updated_time	string (date-time)	The timestamp (in RFC 3339 format) when the user was last updated in the Posit Connect server Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Lock a user

POST /v1/users/{guid}/lock

This endpoint locks or unlocks a given user account.

• Unlocking a user is prohibited if that additional user would violate the user account limit specified by the Posit Connect product license.
• Administrator access is required to access this endpoint.
• Users are able to lock themselves.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that must be specified when locking or unlocking a user.

Name	Type	Description
locked	boolean|null	Whether or not the user should be locked. Example: true.

Responses

200

200: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Search for user details from a remote provider

GET /v1/users/remote

This endpoint is used to support operations against users who do not have a Posit Connect account, such as creating LDAP and OAuth2 with Google users. See GET /v1/users for listing users.

This endpoint searches for users on Posit Connect and on your LDAP or OAuth2 with Google system.

Results are first sorted based on similarity to the prefix and then by first name, last name, username, and email.

• This endpoint can be used only by LDAP or OAuth2 with Google authentication and will return an error otherwise.
• Publisher or administrator access is required to access this endpoint.
• The email field is not populated for non-admins when Server.HideEmailAddresses is enabled.
• The external_id field is only visible to administrators and to users viewing their own record.
• When the user making the request is a viewer and Authorization.ViewersCanOnlySeeThemselves is being used, the results contain only the given user.

Parameters

Name	Type	Description
prefix	string
limit	integer

Responses

200

200: Successful response.

The remote user search results with paging information.

Name	Type	Description
current_page	integer	The current page of results Example: 1.
total	integer	The number of items that match the given filters Example: 1.
results	[object]	The users list
results[].email	string	The user’s email. Example: jon.doe@example.com.
results[].username	string	The user’s username. Example: jondoe.
results[].first_name	string	The user’s first name. Example: Jon.
results[].last_name	string	The user’s last name. Example: Doe.
results[].user_role	string	The user’s role. Enum: administrator, publisher, viewer. Example: administrator.
results[].created_time	string (date-time)	The timestamp (RFC3339) indicating when the user was created in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].updated_time	string (date-time)	The timestamp (RFC3339) indicating when information about this user was last updated in the Posit Connect server. Example: 2006-01-02T15:04:05-07:00.
results[].active_time	string (date-time)|null	The timestamp (RFC3339) indicating approximately when the user was last active. Highly active users only receive periodic updates. Example: 2006-01-02T15:04:05-07:00.
results[].confirmed	boolean	When false, the created user must confirm their account through an email. This feature is unique to password authentication. Example: true.
results[].locked	boolean	Whether or not the user is locked. Example: false.
results[].external_id	string	The unique identifier for this user from the authentication provider, when available. Example: okta-12345-abcde.
results[].guid	string (uuid)|null	The user’s GUID, or unique identifier in RFC4122 format. When a user does not exist in the Posit Connect server, this property will be null. Example: 6f300623-1e0c-48e6-a473-ddf630c0c0c3.
results[].temp_ticket	string	This value is for actions that require a temp_ticket, such as adding an LDAP or OAuth2 with Google user to the Connect server.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

403

403: You do not have permission to perform this operation.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Vanity URLs

Get vanity URL

GET /v1/content/{guid}/vanity

Get the vanity URL, if any, defined for this content. If the content item has a vanity URL, it is returned. If there is no vanity URL for this content, a 404 status is returned.

Administrators can get the vanity URL for any content item. Any authenticated user who is authorized to view the content can get the vanity URL.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

200

200: Successful response.

The fields that are returned when getting or listing vanity URLs.

Name	Type	Description
content_guid	string (uuid)	The unique identifier of the associated content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
path	string	The URL path that will be used by this application. HTTP requests to this path on the Connect server will be routed to the associated content item. Example: /stock-report/.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this vanity URL was created. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Set vanity URL

PUT /v1/content/{guid}/vanity

Set the vanity URL for this content item.

A vanity URL path must meet certain requirements:

• It must consist of alphanumeric characters, hyphens, underscores, and slashes.

• It cannot be a reserved path such as the root path /, or a path beginning with /__.

• The following path prefixes are prohibited:

  • /__
  • /favicon.ico
  • /connect
  • /apps
  • /users
  • /groups
  • /setpassword
  • /user-completion
  • /confirm
  • /recent
  • /reports
  • /plots
  • /unpublished
  • /settings
  • /metrics
  • /tokens
  • /help
  • /login
  • /welcome
  • /register
  • /resetpassword
  • /content
  • The custom location for the Connect dashboard, configured by Server.DashboardPath.

• It cannot be an ancestor or descendant of an existing vanity URL path. For example, if the vanity path /a/b/ exists, you cannot add /a/ or /a/b/c/.

If Authorization.PublishersCanManageVanities is true (default), publishers can set the vanity URL for content items that they have permission to change. Otherwise, administrator permissions are required.

You can reassign an existing vanity URL to a different content item, if you are an administrator or collaborator/owner of both content items. You must set the force parameter to true to reassign a URL. An error will be returned if force is false and the URL already exists.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Request body

The fields that can be specified when creating a vanity URL.

Name	Type	Description
path	string	The URL path that will be assigned to this content item. HTTP requests to this path on the Connect server will be routed to the associated content item. Example: /stock-report/.
force	boolean	If true, and a vanity URL exists with the specified path, reassign it to the specified content item. To reassign a vanity URL, you must be an administrator, or a collaborator/owner of both content items.

Responses

200

200: Successful response.

The fields that are returned when getting or listing vanity URLs.

Name	Type	Description
content_guid	string (uuid)	The unique identifier of the associated content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
path	string	The URL path that will be used by this application. HTTP requests to this path on the Connect server will be routed to the associated content item. Example: /stock-report/.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this vanity URL was created. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

409

409: The request could not be completed due to a conflict.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

Delete vanity URL

DELETE /v1/content/{guid}/vanity

Delete the vanity URL for this content.

If Authorization.PublishersCanManageVanities is true (default), publishers can delete the vanity URL for content items that they have permission to change. Otherwise, administrator permissions are required.

Parameters

Name	Type	Description
guid	string (uuid)	Required.

Responses

204

204: Successful response.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

List vanity URLs

GET /v1/vanities

List all defined vanity URLs.

You must have administrator privileges to perform this action.

Responses

200

200: Successful response.

Array of objects:

The fields that are returned when getting or listing vanity URLs.

Name	Type	Description
content_guid	string (uuid)	The unique identifier of the associated content item. Example: 25438b83-ea6d-4839-ae8e-53c52ac5f9ce.
path	string	The URL path that will be used by this application. HTTP requests to this path on the Connect server will be routed to the associated content item. Example: /stock-report/.
created_time	string (date-time)	The timestamp (RFC3339) indicating when this vanity URL was created. Example: 2006-01-02T15:04:05-07:00.

400

400: The requested operation is invalid.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

401

401: The requested operation requires authentication.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

404

404: The requested object does not exist.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.

500

500: A server error occurred.

The error object returned by the API on failure.

Name	Type	Description
code	integer	The specific code for the type of error returned. See the API error codes reference for the full set of values. Required.
error	string	A description of the problem that was encountered. Required.
payload	object|null	Additional error details, if any. The structure varies by error type.