Get an app's listing
The apps.listing.get operation: GET /api/v1/apps/{id}/listing in the REST API and the apps_listing_get tool in the MCP server.
/api/v1/apps/{id}/listingReturns the listing of one of your organization's registered apps: the review status, whether it is listed
for every organization (a verified publisher) and for which scopes (approvedScopes; pendingScopes wait for
review), the last decision's reason, your application, its history, and the current security questionnaire
to answer with apps.listing.submit.
Statuses: not_submitted (no application yet, or withdrawn), pending (Ownrecord reviews it),
changes_requested (edit the application and submit it again), approved, rejected. An approved app stays
listed for its approved scopes while scopes it added are reviewed again.
At a glance
- REST:
GET /api/v1/apps/{id}/listing - MCP tool:
apps_listing_get - Operation ID:
apps.listing.get - Scope: Organization
- Permission:
agents:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Authentication: API key with the
agents:readscope - Since: M13
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | ocl_… ID |
Query parameters
This operation takes no query parameters.
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | ocl_… ID | |
object | "app_listing" | |
ownerOrgId | org_… ID | |
name | string | |
publisher | string | |
visibility | one of private, listed | |
appStatus | one of active, disabled | |
status | one of not_submitted, pending, changes_requested, approved, rejected | |
listed | boolean | |
scopes | array of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) | |
approvedScopes | array of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) or null | |
pendingScopes | array of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) | |
submittedAt | date-time or null | |
decidedAt | date-time or null | |
reason | string or null | |
application | object or null | |
history | array of object | |
history[].action | one of submitted, withdrawn, approved, rejected, changes_requested, scopes_added, identity_changed, unlisted | |
history[].at | date-time | |
history[].by | string or null | |
history[].reason | string or null | |
history[].scopes | array of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) | |
version | integer | |
questionnaire | object | |
questionnaire.version | integer | |
questionnaire.status | one of proposed, confirmed | |
questionnaire.questions | array of object | |
questionnaire.questions[].id | string | |
questionnaire.questions[].type | one of yes_no, text | |
questionnaire.questions[].required | boolean | |
questionnaire.questions[].text | string | |
questionnaire.questions[].detailsRequiredWhen | one of yes, no or null | |
questionnaire.questions[].hint | string or null |
Examples
An application waiting for review
GET /api/v1/apps/ocl_01m4ttwd3veh9apbewxheq5xha/listing
Authorization: Bearer or_test_…
Response (200):
{
"id": "ocl_01m4ttwd3veh9apbewxheq5xha",
"object": "app_listing",
"ownerOrgId": "org_01m4ttwd3veh9apbewxheq5xhb",
"name": "Ledgerly AI",
"publisher": "Ledgerly AI B.V.",
"visibility": "listed",
"appStatus": "active",
"status": "pending",
"listed": false,
"scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write", "ledger:read"],
"approvedScopes": null,
"pendingScopes": ["filings:read", "filings:write", "tasks:read", "tasks:write", "ledger:read"],
"submittedAt": "2026-10-30T09:00:00.000Z",
"decidedAt": null,
"reason": null,
"application": {
"publisher": {
"legalName": "Ledgerly AI B.V.",
"country": "NL",
"websiteUrl": "https://ledgerly.example",
"contact": {
"name": "Mira de Vries",
"email": "partners@ledgerly.example"
}
},
"privacyPolicyUrl": "https://ledgerly.example/privacy",
"questionnaire": {
"version": 1,
"answers": [
{
"questionId": "data_location",
"answer": null,
"details": "AWS eu-central-1 (Frankfurt), Germany"
},
{
"questionId": "encryption_in_transit",
"answer": "yes",
"details": null
},
{
"questionId": "encryption_at_rest",
"answer": "yes",
"details": null
},
{
"questionId": "credential_storage",
"answer": "yes",
"details": null
},
{
"questionId": "staff_access",
"answer": "yes",
"details": null
},
{
"questionId": "incident_response",
"answer": "yes",
"details": null
},
{
"questionId": "subprocessors",
"answer": "yes",
"details": "AWS (hosting), Postmark (email)"
},
{
"questionId": "model_training",
"answer": "no",
"details": null
},
{
"questionId": "data_deletion",
"answer": "yes",
"details": "Within 30 days of uninstalling"
},
{
"questionId": "vulnerability_management",
"answer": "yes",
"details": null
}
]
},
"scopeJustifications": [
{
"scope": "filings:read",
"justification": "Reads filing periods to prepare each return."
},
{
"scope": "filings:write",
"justification": "Records the prepared return and its submission."
},
{
"scope": "tasks:read",
"justification": "Finds the filing tasks assigned to the app."
},
{
"scope": "tasks:write",
"justification": "Claims and completes filing tasks."
},
{
"scope": "ledger:read",
"justification": "Reconciles the return with the tax payable accounts."
}
],
"partnerTermsVersion": "1.0",
"submittedBy": "usr_01m4ttwd3veh9apbewxheq5xhf"
},
"history": [
{
"action": "submitted",
"at": "2026-10-30T09:00:00.000Z",
"by": "usr_01m4ttwd3veh9apbewxheq5xhf",
"reason": null,
"scopes": []
}
],
"version": 3,
"questionnaire": {
"version": 1,
"status": "proposed",
"questions": [
{
"id": "data_location",
"type": "text",
"required": true,
"text": "Where do you store and process organizations' data? Name the countries and hosting providers.",
"detailsRequiredWhen": null,
"hint": null
}
]
}
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
resource_not_found | 404 | Your organization registered no app with this ID. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
permission_denied | 403 | You can't see the organization's apps. | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.