List OAuth apps API
The List OAuth apps API returns the OAuth apps registered for a project. Use it to discover which apps are available before connecting an account, to filter OAuth apps by platform, to search OAuth apps by name, and to paginate a larger set of results. Each returned app includes its identifier, platform, name, imageUrl, clientId, integrationCount, createdAt, and updatedAt values, so a client can present the right app and use its id as appId when connecting.
Operation summary: GET /v1/apps/
The operation is GET /v1/apps/. It lists registered OAuth apps for the project identified by the request credentials. Call it without query parameters to retrieve the first page using the defaults, or add the optional query parameters described below to narrow or paginate the result set. The successful response uses status 200 with an application/json body containing success, total, page, limit, and apps. The apps array contains one object per matching OAuth app, and total reports the overall count for the query while page and limit echo the pagination window used for the response.
Authorization
Send the access key in the x-access-key header on every request. The header value is the token placeholder shown in the request example titled List OAuth apps request. Keep the token out of query strings and out of logs, and treat a missing or invalid header as a client-side failure to check before debugging filters or pagination. No other authorization header is specified for this operation.
Query parameters field map
All four query parameters are optional. Use platform to restrict results to one platform value from the stated enum, page to choose the result page, limit to choose how many apps to return per page, and name to match a case-insensitive substring of the app name. When you combine filters, the response total reflects the combined query, so verify total, page, and limit together rather than assuming the length of the apps array is the full result count. The field map titled Query parameters field map lists the type, requiredness, default, range, enum, and length constraint for each parameter, and the validation matrix titled Validation and pagination checks lists the checks derived only from those stated constraints.
Response body field map
In the 200 response, success is a required boolean, total is a required integer with a minimum of 0, page is a required integer with a minimum of 1, limit is a required integer with a minimum of 1, and apps is a required array of app objects. Each app object requires id as a string, platform as a string from the same platform enum, name as a string, imageUrl as string or null, clientId as a string, integrationCount as an integer with a minimum of 0, and createdAt and updatedAt as date-time strings. Use id as appId when connecting, use clientId to identify the OAuth app client, and use integrationCount to see how many active integrations are connected under that app. The client secret is never returned in this response. The field map titled Response body field map gives the complete type and requiredness detail, and the example titled 200 application/json response example shows the exact success shape.
Request and response workflow
Build the request with the origin placeholder followed by the unchanged path /v1/apps/, add the x-access-key header, and append query parameters only when filtering or paginating. After a 200 response, read success first, then use total to decide whether more pages exist, and iterate by increasing page while keeping limit within its stated range. For each app, preserve imageUrl as nullable, format createdAt and updatedAt as date-time values, and do not expect a client secret field. If the apps array is empty, treat that as a valid empty result for the current filters and adjust platform or name before assuming no apps are registered.
Validation and pagination notes
Validate inputs against the stated constraints before sending: platform must be one of the listed enum values, page must be at least 1, limit must be between 1 and 100, and name must be between 1 and 200 characters when supplied. Check that the response contains the required top-level fields and that every app object contains its required fields with the stated types, including a nullable imageUrl and date-time createdAt and updatedAt. Because no error-response contract beyond the 200 response is specified here, do not invent error bodies or retry rules; instead, surface unexpected statuses to the caller and re-check the header, path, and parameter constraints first.
| Parameter | Required | Type | Default / constraint | Use |
|---|---|---|---|---|
| platform | Optional | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | Filter OAuth apps by platform |
| page | Optional | integer | Default 1; 1 <= value | Select the result page |
| limit | Optional | integer | Default 50; 1 <= value <= 100 | Set page size |
| name | Optional | string | 1 <= length <= 200; case-insensitive substring match on app name | Search OAuth apps by name |
All parameters are optional per the source contract.
| Field | Required | Type | Constraint / note |
|---|---|---|---|
| success | Required | boolean | Top-level result flag |
| total | Required | integer | 0 <= value |
| page | Required | integer | 1 <= value |
| limit | Required | integer | 1 <= value |
| apps | Required | array<object> | Array of app objects |
| apps[].id | Required | string | Pass this as appId when connecting |
| apps[].platform | Required | string | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" |
| apps[].name | Required | string | App name |
| apps[].imageUrl | Required | string | null | Nullable image URL |
| apps[].clientId | Required | string | OAuth app client id; client secret is never returned |
| apps[].integrationCount | Required | integer | 0 <= value; number of active integrations connected under this app |
| apps[].createdAt | Required | string | date-time format |
| apps[].updatedAt | Required | string | date-time format |
Response status is 200 with application/json.
| Check | Stated constraint | Client action |
|---|---|---|
| Authorization header present | x-access-key header with <token> | Send the header on every request |
| platform value | Must be one of the listed enum values | Omit platform or use an exact enum value |
| page value | 1 <= value; default 1 | Use an integer of at least 1 |
| limit value | 1 <= value <= 100; default 50 | Use an integer within the range |
| name value | 1 <= length <= 200 | Omit name or keep it within the length range |
| Pagination completeness | total, page, and limit are required in the response | Compare total with page and limit before stopping |
| App object completeness | All nested app fields are required; imageUrl is string | null | Handle null imageUrl and date-time createdAt/updatedAt |
Derived only from stated constraints; no error contract invented.
curl -X GET "{{API_BASE_URL}}/v1/apps/" \
-H "x-access-key: <token>"curl -X GET "{{API_BASE_URL}}/v1/apps/?platform=twitter&page=1&limit=50&name=example" \
-H "x-access-key: <token>"{
"success": true,
"total": 0,
"page": 1,
"limit": 1,
"apps": [
{
"id": "string",
"platform": "twitter",
"name": "string",
"imageUrl": "string",
"clientId": "string",
"integrationCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| platform#1 | platform | string | __0 | No | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| page#2 | page | integer | __0 | No | kind: schemaDefault; value: 1 | kind: schemaRange; value: 1 <= value | |
| limit#3 | limit | integer | __0 | No | kind: schemaDefault; value: 50 | kind: schemaRange; value: 1 <= value <= 100 | |
| name#4 | name | string | __0 | No | Case-insensitive substring match on app name | kind: schemaLength; value: 1 <= length <= 200 |
| response#5 | response | object | __0 | |||
| response#5 | response.success | boolean | __1 | Yes | ||
| response#5 | response.total | integer | __2 | Yes | kind: schemaRange; value: 0 <= value | |
| response#5 | response.page | integer | __3 | Yes | kind: schemaRange; value: 1 <= value | |
| response#5 | response.limit | integer | __4 | Yes | kind: schemaRange; value: 1 <= value | |
| response#5 | response.apps | array<object> | __5 | Yes | ||
| response#5 | response.apps[] | object | __6 | |||
| response#5 | response.apps[].id | string | __7 | Yes | Pass this as appId when connecting | |
| response#5 | response.apps[].platform | string | __8 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| response#5 | response.apps[].name | string | __9 | Yes | ||
| response#5 | response.apps[].imageUrl | string | null | __10 | Yes | ||
| response#5 | response.apps[].imageUrl[variant1] | string | __10_type:string | |||
| response#5 | response.apps[].imageUrl[variant2] | null | __10_type:null | |||
| response#5 | response.apps[].clientId | string | __11 | Yes | The OAuth app client id. The client secret is never returned. | |
| response#5 | response.apps[].integrationCount | integer | __12 | Yes | Number of active integrations connected under this app | kind: schemaRange; value: 0 <= value |
| response#5 | response.apps[].createdAt | string | __13 | Yes | kind: schemaFormat; value: date-time | |
| response#5 | response.apps[].updatedAt | string | __14 | Yes | kind: schemaFormat; value: date-time |