Skip to content

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.

GET/api/v1/apps/{id}/listing

Returns 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:read scope
  • Since: M13

Request

Path parameters

FieldTypeDescription
idocl_… ID

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

FieldTypeDescription
idocl_… ID
object"app_listing"
ownerOrgIdorg_… ID
namestring
publisherstring
visibilityone of private, listed
appStatusone of active, disabled
statusone of not_submitted, pending, changes_requested, approved, rejected
listedboolean
scopesarray of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document)
approvedScopesarray of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) or null
pendingScopesarray of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document)
submittedAtdate-time or null
decidedAtdate-time or null
reasonstring or null
applicationobject or null
historyarray of object
history[].actionone of submitted, withdrawn, approved, rejected, changes_requested, scopes_added, identity_changed, unlisted
history[].atdate-time
history[].bystring or null
history[].reasonstring or null
history[].scopesarray of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document)
versioninteger
questionnaireobject
questionnaire.versioninteger
questionnaire.statusone of proposed, confirmed
questionnaire.questionsarray of object
questionnaire.questions[].idstring
questionnaire.questions[].typeone of yes_no, text
questionnaire.questions[].requiredboolean
questionnaire.questions[].textstring
questionnaire.questions[].detailsRequiredWhenone of yes, no or null
questionnaire.questions[].hintstring or null

Examples

An application waiting for review

HTTP
GET /api/v1/apps/ocl_01m4ttwd3veh9apbewxheq5xha/listing
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "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

CodeHTTP statusWhenWhat to do
resource_not_found404Your 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_denied403You 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.