---
title: API descriptors
description: Common REST endpoints in PingGateway serve API descriptors at runtime. When you retrieve an API descriptor for an endpoint, a JSON that describes the API for that endpoint is returned.
component: pinggateway
version: 2025.3
page_id: pinggateway:about:api-descriptor
canonical_url: https://docs.pingidentity.com/pinggateway/2026/about/api-descriptor.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
superseded_by: https://docs.pingidentity.com/pinggateway/2026/about/api-descriptor.html
section_ids:
  retrieve_api_descriptors_for_a_router: Retrieve API descriptors for a router
  retrieve_api_descriptors_for_the_uma_service: Retrieve API descriptors for the UMA service
  retrieve_api_descriptors_for_the_main_router: Retrieve API descriptors for the main router
  retrieve_api_descriptors_for_pinggateway_instances: Retrieve API descriptors for PingGateway instances
---

# API descriptors

Common REST endpoints in PingGateway serve API descriptors at runtime. When you retrieve an API descriptor for an endpoint, a JSON that describes the API for that endpoint is returned.

To discover and understand APIs, use the API descriptor with a tool such as [Swagger UI](https://swagger.io/tools/swagger-ui/) to generate a web page that helps you to view and test the different endpoints.

When you start PingGateway, or add or edit routes, registered endpoint locations for the routes hosted by the main router are written in `$HOME/.openig/logs/route-system.log`, where `$HOME/.openig` is the instance directory. Endpoint locations for subroutes are written to other log files. To retrieve the API descriptor for a specific endpoint, append one of the following query string parameters to the endpoint:

* `_api`, to represent the API accessible over HTTP. This OpenAPI descriptor can be used with endpoints that are complete or partial URLs.

  The returned JSON respects the OpenAPI specification and can be consumed by Swagger tools, such as [Swagger UI](https://swagger.io/tools/swagger-ui/).

* `_crestapi`, to provide a compact representation that is independent of the transport protocol. This ForgeRock® Common REST (Common REST) API descriptor can't be used with partial URLs.

  The returned JSON respects a ForgeRock proprietary specification dedicated to describe Common REST endpoints.

For more information about Common REST API descriptors, refer to [Common REST API documentation](../reference/preface.html#about-crest-api-descriptors).

## Retrieve API descriptors for a router

|   |                                                                                                                     |
| - | ------------------------------------------------------------------------------------------------------------------- |
|   | Switch to [development mode](../configure/operating-modes.html#development-mode) to retrieve these API descriptors. |

With PingGateway running as described in the [Quick install](../getting-started/preface.html), run the following query to generate a JSON that describes the router operations supported by the endpoint:

```console
$ curl http://ig.example.com:8085/api/system/objects/_router/routes\?_api
```

Output

```
{
     "swagger": "2.0",
     "info": {
     "version": "IG version",
     "title": "IG"
     },
     "host": "0:0:0:0:0:0:0:1",
     "basePath": "/api/system/objects/_router/routes",
     "tags": [{
     "name": "Routes Endpoint"
     }],
     . . .
```

Alternatively, generate a Common REST API descriptor by using the `?_crestapi` query string.

## Retrieve API descriptors for the UMA service

|   |                                                                                                                     |
| - | ------------------------------------------------------------------------------------------------------------------- |
|   | Switch to [development mode](../configure/operating-modes.html#development-mode) to retrieve these API descriptors. |

With the UMA tutorial running as described in [UMA support](../gateway-guide/uma.html), run the following query to generate a JSON that describes the UMA share API:

```console
$ curl http://ig.example.com:8085/api/system/objects/_router/routes/00-uma/objects/umaservice/share\?_api
```

Output

```
{
     "swagger": "2.0",
     "info": {
     "version": "IG version",
     "title": "IG"
     },
     "host": "0:0:0:0:0:0:0:1",
     "basePath": "/api/system/objects/_router/routes/00-uma/objects/umaservice/share",
     "tags": [{
     "name": "Manage UMA Share objects"
     }],
     . . .
```

Alternatively, generate a Common REST API descriptor by using the `?_crestapi` query string.

## Retrieve API descriptors for the main router

Run a query to generate a JSON that describes the API for the main router and its subsequent endpoints. For example:

```console
$ curl http://ig.example.com:8085/api/system/objects/_router\?_api
```

Output

```
{
     "swagger": "2.0",
     "info": {
     "version": "IG version",
     "title": "IG"
     },
     "host": "{gatewayUrl}:8085",
     "basePath": "/api/system/objects/_router",
     "tags": [{
     "name": "Monitoring endpoint"
     }, {
     "name": "Manage UMA Share objects"
     }, {
     "name": "Routes Endpoint"
     }],
     . . .
```

Because the above URL is a partial URL, you cannot use the `?_crestapi` query string to generate a Common REST API descriptor.

## Retrieve API descriptors for PingGateway instances

Run a query to generate a JSON that describes the APIs provided by the PingGateway instance that's responding to a request. For example:

```console
$ curl http://ig.example.com:8085/api\?_api
```

Output

```
{
     "swagger": "2.0",
     "info": {
     "version": "IG version",
     "title": "IG"
     },
     "host": "{gatewayUrl}:8085",
     "basePath": "/api",
     "tags": [{
     "name": "Internal Storage for UI Models"
     }, {
     "name": "Monitoring endpoint"
     }, {
     "name": "Manage UMA Share objects"
     }, {
     "name": "Routes Endpoint"
     }, {
     "name": "Server Info"
     }],
     . . .
```

If routes are added after the request is performed, they aren't included in the returned JSON.

Because the above URL is a partial URL, you can't use the `?_crestapi` query string to generate a Common REST API descriptor.