Connect apps service#
Service for creating and managing Connect Apps
OpenAPI file: nominal.connect.v1.json
Endpoints#
Create connect app#
POST /connect/v1/apps
Create a new Connect App, either with a bundle file or as an empty app
Body
displayNamestringseparate from the bundle title to allow for creating empty apps At least 1 character.
descriptionstring
labelsarray of string
propertiesmap of string to string
isPublishedboolean
workspacestring
bundleConnectAppBundleoptional to allow for creating “empty” in-progress connect apps
Fields of
ConnectAppBundles3PathHandle
Fields of
Handles3string
metadataConnectAppBundleMetadata
Fields of
ConnectAppBundleMetadatatitlestring
containsExperimentalFeaturesboolean
sha256Checksumstring
connectFilePathstringname of the .connect file inside the bundle. Will default to app.connect
commitMessagestring
Response
appConnectApp
Fields of
ConnectAppridstring
commitstring
metadataConnectAppMetadata
Fields of
ConnectAppMetadataridstring
displayNamestring
descriptionstring
labelsarray of string
propertiesmap of string to string
isArchivedboolean
isPublishedboolean
createdAtstring (date-time)
createdBystring
updatedAtstring (date-time)
workspacestring
bundleConnectAppBundle
Fields of
ConnectAppBundles3PathHandle
Fields of
Handles3string
metadataConnectAppBundleMetadata
Fields of
ConnectAppBundleMetadatatitlestring
containsExperimentalFeaturesboolean
sha256Checksumstring
connectFilePathstringname of the .connect file inside the bundle. Will default to app.connect
versionNumberstring (uint64)
Request
curl -X POST "https://api.gov.nominal.io/api/connect/v1/apps" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"displayName": "<display name>",
"description": "<description>",
"labels": [
"<labels>"
],
"properties": {
"<key>": "<value>"
},
"isPublished": true,
"workspace": "<workspace>",
"bundle": {
"s3Path": {
"s3": "<s3>"
},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": true,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>"
}
},
"commitMessage": "<commit message>"
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/connect/v1/apps",
headers={"Authorization": "Bearer <api key>"},
json={
"displayName": "<display name>",
"description": "<description>",
"labels": ["<labels>"],
"properties": {"<key>": "<value>"},
"isPublished": True,
"workspace": "<workspace>",
"bundle": {
"s3Path": {"s3": "<s3>"},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": True,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>",
},
},
"commitMessage": "<commit message>",
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/connect/v1/apps",
headers={"Authorization": "Bearer <api key>"},
json={
"displayName": "<display name>",
"description": "<description>",
"labels": ["<labels>"],
"properties": {"<key>": "<value>"},
"isPublished": True,
"workspace": "<workspace>",
"bundle": {
"s3Path": {"s3": "<s3>"},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": True,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>",
},
},
"commitMessage": "<commit message>",
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/connect/v1/apps",
headers={"Authorization": "Bearer <api key>"},
json={
"displayName": "<display name>",
"description": "<description>",
"labels": ["<labels>"],
"properties": {"<key>": "<value>"},
"isPublished": True,
"workspace": "<workspace>",
"bundle": {
"s3Path": {"s3": "<s3>"},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": True,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>",
},
},
"commitMessage": "<commit message>",
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"app": {
"rid": "<rid>",
"commit": "<commit>",
"metadata": {
"rid": "<rid>",
"displayName": "<display name>",
"description": "<description>",
"labels": [
"<labels>"
],
"properties": {
"<key>": "<value>"
},
"isArchived": true,
"isPublished": true,
"createdAt": "2026-01-01T00:00:00Z",
"createdBy": "<created by>",
"updatedAt": "2026-01-01T00:00:00Z",
"workspace": "<workspace>"
},
"bundle": {
"s3Path": {
"s3": "<s3>"
},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": true,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>"
}
},
"versionNumber": "1"
}
}
Archive connect apps#
POST /connect/v1/apps/archive
Archive Connect Apps
Body
ridsarray of string
Response
ridsarray of string
Request
curl -X POST "https://api.gov.nominal.io/api/connect/v1/apps/archive" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"rids": [
"<rids>"
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/connect/v1/apps/archive",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/connect/v1/apps/archive",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/connect/v1/apps/archive",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"rids": [
"<rids>"
]
}
Search connect apps#
POST /connect/v1/apps/search
Searches for Connect Apps, returning paged results. Workspaces the caller lacks workspace:view on are filtered out rather than failing the call.
Body
queryConnectAppSearchQuery
Fields of
ConnectAppSearchQuery- one of 7 fields required
searchTextstring
labelstring
propertyProperty
Fields of
Propertynamestring
valuestring
andConnectAppSearchAndQuery
Fields of
ConnectAppSearchAndQueryqueriesarray ofConnectAppSearchQuery
orConnectAppSearchOrQuery
Fields of
ConnectAppSearchOrQueryqueriesarray ofConnectAppSearchQuery
workspacestring
isArchivedboolean
optionsSearchConnectAppsOptions
Fields of
SearchConnectAppsOptionsisDescendingbooleandefault is true
sortFieldSearchConnectAppsSortFielddefault is title
Values of
SearchConnectAppsSortFieldSEARCH_CONNECT_APPS_SORT_FIELD_UNSPECIFIED
SEARCH_CONNECT_APPS_SORT_FIELD_TITLE
SEARCH_CONNECT_APPS_SORT_FIELD_CREATED_AT
SEARCH_CONNECT_APPS_SORT_FIELD_DISPLAY_NAME
pageSizeintegerFrom 1 to 1,000.
nextPageTokenstring
Response
appMetadataarray ofConnectAppMetadata
Fields of
ConnectAppMetadataridstring
displayNamestring
descriptionstring
labelsarray of string
propertiesmap of string to string
isArchivedboolean
isPublishedboolean
createdAtstring (date-time)
createdBystring
updatedAtstring (date-time)
workspacestring
nextPageTokenstring
Request
curl -X POST "https://api.gov.nominal.io/api/connect/v1/apps/search" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"query": {
"searchText": "<search text>"
},
"options": {
"isDescending": true,
"sortField": "SEARCH_CONNECT_APPS_SORT_FIELD_TITLE"
},
"pageSize": 1,
"nextPageToken": "<next page token>"
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/connect/v1/apps/search",
headers={"Authorization": "Bearer <api key>"},
json={
"query": {"searchText": "<search text>"},
"options": {
"isDescending": True,
"sortField": "SEARCH_CONNECT_APPS_SORT_FIELD_TITLE",
},
"pageSize": 1,
"nextPageToken": "<next page token>",
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/connect/v1/apps/search",
headers={"Authorization": "Bearer <api key>"},
json={
"query": {"searchText": "<search text>"},
"options": {
"isDescending": True,
"sortField": "SEARCH_CONNECT_APPS_SORT_FIELD_TITLE",
},
"pageSize": 1,
"nextPageToken": "<next page token>",
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/connect/v1/apps/search",
headers={"Authorization": "Bearer <api key>"},
json={
"query": {"searchText": "<search text>"},
"options": {
"isDescending": True,
"sortField": "SEARCH_CONNECT_APPS_SORT_FIELD_TITLE",
},
"pageSize": 1,
"nextPageToken": "<next page token>",
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"appMetadata": [
{
"rid": "<rid>",
"displayName": "<display name>",
"description": "<description>",
"labels": [
"<labels>"
],
"properties": {
"<key>": "<value>"
},
"isArchived": true,
"isPublished": true,
"createdAt": "2026-01-01T00:00:00Z",
"createdBy": "<created by>",
"updatedAt": "2026-01-01T00:00:00Z",
"workspace": "<workspace>"
}
],
"nextPageToken": "<next page token>"
}
Unarchive connect apps#
POST /connect/v1/apps/unarchive
Unarchive Connect Apps
Body
ridsarray of string
Response
ridsarray of string
Request
curl -X POST "https://api.gov.nominal.io/api/connect/v1/apps/unarchive" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"rids": [
"<rids>"
]
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/connect/v1/apps/unarchive",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/connect/v1/apps/unarchive",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/connect/v1/apps/unarchive",
headers={"Authorization": "Bearer <api key>"},
json={"rids": ["<rids>"]},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"rids": [
"<rids>"
]
}
Get connect app#
GET /connect/v1/apps/{rid}
Get a Connect App by its RID
Path parameters
ridstring required
Query parameters
branchOrCommit.branchstring
branchOrCommit.commitstring
Response
appConnectApp
Fields of
ConnectAppridstring
commitstring
metadataConnectAppMetadata
Fields of
ConnectAppMetadataridstring
displayNamestring
descriptionstring
labelsarray of string
propertiesmap of string to string
isArchivedboolean
isPublishedboolean
createdAtstring (date-time)
createdBystring
updatedAtstring (date-time)
workspacestring
bundleConnectAppBundle
Fields of
ConnectAppBundles3PathHandle
Fields of
Handles3string
metadataConnectAppBundleMetadata
Fields of
ConnectAppBundleMetadatatitlestring
containsExperimentalFeaturesboolean
sha256Checksumstring
connectFilePathstringname of the .connect file inside the bundle. Will default to app.connect
versionNumberstring (uint64)
Request
curl "https://api.gov.nominal.io/api/connect/v1/apps/<rid>" \
-H "Authorization: Bearer <api key>"
import requests
response = requests.get(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.get(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.get(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>",
headers={"Authorization": "Bearer <api key>"},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"app": {
"rid": "<rid>",
"commit": "<commit>",
"metadata": {
"rid": "<rid>",
"displayName": "<display name>",
"description": "<description>",
"labels": [
"<labels>"
],
"properties": {
"<key>": "<value>"
},
"isArchived": true,
"isPublished": true,
"createdAt": "2026-01-01T00:00:00Z",
"createdBy": "<created by>",
"updatedAt": "2026-01-01T00:00:00Z",
"workspace": "<workspace>"
},
"bundle": {
"s3Path": {
"s3": "<s3>"
},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": true,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>"
}
},
"versionNumber": "1"
}
}
Get connect app bundle download URL#
GET /connect/v1/apps/{rid}/bundle-download
Get a pre-signed URL for downloading the bundle of a Connect App at a specific commit or the latest commit on the main branch
Path parameters
ridstring required
Query parameters
branchOrCommit.branchstring
branchOrCommit.commitstring
Response
urlstring
Request
curl "https://api.gov.nominal.io/api/connect/v1/apps/<rid>/bundle-download" \
-H "Authorization: Bearer <api key>"
import requests
response = requests.get(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/bundle-download",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.get(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/bundle-download",
headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.get(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/bundle-download",
headers={"Authorization": "Bearer <api key>"},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"url": "<url>"
}
Commit#
POST /connect/v1/apps/{rid}/commit
Commit a bundle to the main branch
Path parameters
ridstring required
Body
bundleConnectAppBundle
Fields of
ConnectAppBundles3PathHandle
Fields of
Handles3string
metadataConnectAppBundleMetadata
Fields of
ConnectAppBundleMetadatatitlestring
containsExperimentalFeaturesboolean
sha256Checksumstring
connectFilePathstringname of the .connect file inside the bundle. Will default to app.connect
messagestring
Response
appConnectApp
Fields of
ConnectAppridstring
commitstring
metadataConnectAppMetadata
Fields of
ConnectAppMetadataridstring
displayNamestring
descriptionstring
labelsarray of string
propertiesmap of string to string
isArchivedboolean
isPublishedboolean
createdAtstring (date-time)
createdBystring
updatedAtstring (date-time)
workspacestring
bundleConnectAppBundle
Fields of
ConnectAppBundles3PathHandle
Fields of
Handles3string
metadataConnectAppBundleMetadata
Fields of
ConnectAppBundleMetadatatitlestring
containsExperimentalFeaturesboolean
sha256Checksumstring
connectFilePathstringname of the .connect file inside the bundle. Will default to app.connect
versionNumberstring (uint64)
Request
curl -X POST "https://api.gov.nominal.io/api/connect/v1/apps/<rid>/commit" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"bundle": {
"s3Path": {
"s3": "<s3>"
},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": true,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>"
}
},
"message": "<message>"
}'
import requests
response = requests.post(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/commit",
headers={"Authorization": "Bearer <api key>"},
json={
"bundle": {
"s3Path": {"s3": "<s3>"},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": True,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>",
},
},
"message": "<message>",
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.post(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/commit",
headers={"Authorization": "Bearer <api key>"},
json={
"bundle": {
"s3Path": {"s3": "<s3>"},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": True,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>",
},
},
"message": "<message>",
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.post(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/commit",
headers={"Authorization": "Bearer <api key>"},
json={
"bundle": {
"s3Path": {"s3": "<s3>"},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": True,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>",
},
},
"message": "<message>",
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"app": {
"rid": "<rid>",
"commit": "<commit>",
"metadata": {
"rid": "<rid>",
"displayName": "<display name>",
"description": "<description>",
"labels": [
"<labels>"
],
"properties": {
"<key>": "<value>"
},
"isArchived": true,
"isPublished": true,
"createdAt": "2026-01-01T00:00:00Z",
"createdBy": "<created by>",
"updatedAt": "2026-01-01T00:00:00Z",
"workspace": "<workspace>"
},
"bundle": {
"s3Path": {
"s3": "<s3>"
},
"metadata": {
"title": "<title>",
"containsExperimentalFeatures": true,
"sha256Checksum": "<sha256 checksum>",
"connectFilePath": "<connect file path>"
}
},
"versionNumber": "1"
}
}
Update connect app metadata#
PUT /connect/v1/apps/{rid}/metadata
Update metadata fields of a Connect App
Path parameters
ridstring required
Body
displayNamestring
descriptionstring
labelsLabelUpdateWrapper
Fields of
LabelUpdateWrapperlabelsarray of string
propertiesPropertyUpdateWrapper
Fields of
PropertyUpdateWrapperpropertiesmap of string to string
isArchivedboolean
isPublishedboolean
Response
appMetadataConnectAppMetadata
Fields of
ConnectAppMetadataridstring
displayNamestring
descriptionstring
labelsarray of string
propertiesmap of string to string
isArchivedboolean
isPublishedboolean
createdAtstring (date-time)
createdBystring
updatedAtstring (date-time)
workspacestring
Request
curl -X PUT "https://api.gov.nominal.io/api/connect/v1/apps/<rid>/metadata" \
-H "Authorization: Bearer <api key>" \
-H "Content-Type: application/json" \
--data '{
"displayName": "<display name>",
"description": "<description>",
"labels": {
"labels": [
"<labels>"
]
},
"properties": {
"properties": {
"<key>": "<value>"
}
},
"isArchived": true,
"isPublished": true
}'
import requests
response = requests.put(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/metadata",
headers={"Authorization": "Bearer <api key>"},
json={
"displayName": "<display name>",
"description": "<description>",
"labels": {"labels": ["<labels>"]},
"properties": {"properties": {"<key>": "<value>"}},
"isArchived": True,
"isPublished": True,
},
)
response.raise_for_status()
print(response.json())
import httpx
response = httpx.put(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/metadata",
headers={"Authorization": "Bearer <api key>"},
json={
"displayName": "<display name>",
"description": "<description>",
"labels": {"labels": ["<labels>"]},
"properties": {"properties": {"<key>": "<value>"}},
"isArchived": True,
"isPublished": True,
},
)
response.raise_for_status()
print(response.json())
import asyncio
import aiohttp
async def main() -> None:
async with aiohttp.ClientSession() as session:
async with session.put(
"https://api.gov.nominal.io/api/connect/v1/apps/<rid>/metadata",
headers={"Authorization": "Bearer <api key>"},
json={
"displayName": "<display name>",
"description": "<description>",
"labels": {"labels": ["<labels>"]},
"properties": {"properties": {"<key>": "<value>"}},
"isArchived": True,
"isPublished": True,
},
) as response:
response.raise_for_status()
print(await response.json())
asyncio.run(main())
Response: 200
{
"appMetadata": {
"rid": "<rid>",
"displayName": "<display name>",
"description": "<description>",
"labels": [
"<labels>"
],
"properties": {
"<key>": "<value>"
},
"isArchived": true,
"isPublished": true,
"createdAt": "2026-01-01T00:00:00Z",
"createdBy": "<created by>",
"updatedAt": "2026-01-01T00:00:00Z",
"workspace": "<workspace>"
}
}
Errors#
Errors shows how these errors are sent.
Each error’s errorName is NominalConnectV1: followed by its name below.
Status |
Name |
Notes |
|---|---|---|
400 |
|
Cannot commit to an archived connect app |
400 |
|
Invalid search token |
404 |
|
Connect app not found |
404 |
|
Connect app commit not found |
404 |
|
Connect app bundle is missing in this commit |
Types#
ConnectApp#
ridstring
commitstring
metadataConnectAppMetadata
bundleConnectAppBundle
versionNumberstring (uint64)
ConnectAppBundle#
s3PathHandle
metadataConnectAppBundleMetadata
ConnectAppBundleMetadata#
wrapper message for metadata that will probably be extended in the future
titlestring
containsExperimentalFeaturesboolean
sha256Checksumstring
connectFilePathstringname of the .connect file inside the bundle. Will default to app.connect
ConnectAppMetadata#
ridstring
displayNamestring
descriptionstring
labelsarray of string
propertiesmap of string to string
isArchivedboolean
isPublishedboolean
createdAtstring (date-time)
createdBystring
updatedAtstring (date-time)
workspacestring
ConnectAppSearchAndQuery#
queriesarray ofConnectAppSearchQuery
ConnectAppSearchOrQuery#
queriesarray ofConnectAppSearchQuery
ConnectAppSearchQuery#
Set exactly one of the fields below.
- one of 7 fields required
Handle#
s3string
LabelUpdateWrapper#
Wrapper classes to allow for optional fields on update requests
labelsarray of string
Property#
namestring
valuestring
PropertyUpdateWrapper#
propertiesmap of string to string
SearchConnectAppsOptions#
isDescendingbooleandefault is true
sortFieldSearchConnectAppsSortFielddefault is title
SearchConnectAppsSortField#
SEARCH_CONNECT_APPS_SORT_FIELD_UNSPECIFIED
SEARCH_CONNECT_APPS_SORT_FIELD_TITLE
SEARCH_CONNECT_APPS_SORT_FIELD_CREATED_AT
SEARCH_CONNECT_APPS_SORT_FIELD_DISPLAY_NAME
Page design based on Scalar, MIT License.