Skip to main content
POST
/
digester
/
{session_id}
/
metadata
Extract Metadata
curl --request POST \
  --url https://api.example.com/digester/{session_id}/metadata
{
  "jobId": "<string>",
  "status": "<string>",
  "result": {
    "result.infoAboutSchema": {
      "result.infoAboutSchema.name": "<string>",
      "result.infoAboutSchema.applicationVersion": "<string>",
      "result.infoAboutSchema.apiVersion": "<string>",
      "result.infoAboutSchema.apiType": [
        {}
      ],
      "result.infoAboutSchema.baseApiEndpoint": [
        {
          "result.infoAboutSchema.baseApiEndpoint[].uri": "<string>",
          "result.infoAboutSchema.baseApiEndpoint[].type": "<string>"
        }
      ]
    }
  },
  "status_code": 123,
  "detail": "<string>"
}
Extract high-level API metadata from documentation including product name, API version, API type (REST, GraphQL, SOAP, etc.), and base API endpoints.

​
Request

​
session_id
string
required
Session ID (UUID format)
​
use_previous_session_data
boolean
default:"true"
Whether to use previous session data if available

​
Response

Returns a job ID to poll for results.
​
jobId
string
Job ID (UUID) to track extraction progress

​
Example Request

curl -X POST "https://api.example.com/digester/550e8400-e29b-41d4-a716-446655440000/metadata" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000"
}

​
Get Metadata Status

Get the status and results of the metadata extraction job.

​
Request

​
session_id
string
required
Session ID (UUID format)
​
jobId
string
Job ID (optional, will use session’s job if not provided)

​
Response

​
status
string
Job status: pending, running, finished, or failed
​
result
object
Extraction results (available when status is finished)
​
result.infoAboutSchema
object
High-level application and API metadata
​
result.infoAboutSchema.name
string
Application or product name as stated in the documentation
​
result.infoAboutSchema.applicationVersion
string
Application version label if provided
​
result.infoAboutSchema.apiVersion
string
API version string (e.g., “v1”, “2024-05”, “1.2.3”)
​
result.infoAboutSchema.apiType
array
API technology types: REST, OpenAPI, SCIM, SOAP, GraphQL, Other
​
result.infoAboutSchema.baseApiEndpoint
array
One or more base endpoints with their classification
​
result.infoAboutSchema.baseApiEndpoint[].uri
string
Base URL or URI template (e.g., “https://api.example.com/v1”)
​
result.infoAboutSchema.baseApiEndpoint[].type
string
Either constant (same for all deployments) or dynamic (varies per tenant/installation)

​
Example Request

curl -X GET "https://api.example.com/digester/550e8400-e29b-41d4-a716-446655440000/metadata?jobId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "status": "finished",
  "result": {
    "infoAboutSchema": {
      "name": "Acme Identity Platform",
      "applicationVersion": "2024.1",
      "apiVersion": "v2",
      "apiType": ["REST", "OpenAPI"],
      "baseApiEndpoint": [
        {
          "uri": "https://api.acme.com/v2",
          "type": "constant"
        }
      ]
    }
  }
}

​
Metadata Fields

​
Product Name

The name of the API or product as it appears in the documentation. 
{
  "name": "Acme Identity Platform"
}

​
Application Version

The version of the application or product itself (not the API version). 
{
  "applicationVersion": "2024.1"
}

​
API Version

The specific version of the API being documented. 
{
  "apiVersion": "v2"
}
Common formats:
  • Semantic versioning: 1.2.3
  • Simple versioning: v1, v2
  • Date-based: 2024-05, 2024-01-15

​
API Type

The technology or protocol used by the API. 
{
  "apiType": ["REST", "OpenAPI"]
}
Possible values:
  • REST - RESTful API
  • OpenAPI - OpenAPI/Swagger specification
  • SCIM - System for Cross-domain Identity Management
  • SOAP - Simple Object Access Protocol
  • GraphQL - GraphQL API
  • Other - Other types

​
Base API Endpoint

The base URL(s) for accessing the API. 
{
  "baseApiEndpoint": [
    {
      "uri": "https://api.example.com/v1",
      "type": "constant"
    },
    {
      "uri": "https://{tenant}.example.com/api",
      "type": "dynamic"
    }
  ]
}
Constant endpoints: Same URL for all users/deployments
  • Example: https://api.github.com
Dynamic endpoints: URL varies by tenant or installation
  • Example: https://{tenant}.okta.com (where {tenant} is customer-specific)
  • Example: https://your-domain.auth0.com (self-hosted)

​
Usage in Endpoint Extraction

The metadata extraction is particularly important for endpoint extraction. When you extract endpoints for an object class using /classes/{object_class}/endpoints, the system automatically:
  1. Loads the baseApiEndpoint from metadata
  2. Uses it to construct complete endpoint URLs
  3. Provides context for understanding endpoint paths
This is why it’s recommended to run metadata extraction early in your workflow.

​
Example: Multi-Region API

{
  "status": "finished",
  "result": {
    "infoAboutSchema": {
      "name": "Global Identity Service",
      "applicationVersion": "3.0.0",
      "apiVersion": "v3",
      "apiType": ["REST", "OpenAPI"],
      "baseApiEndpoint": [
        {
          "uri": "https://us.api.example.com/v3",
          "type": "constant"
        },
        {
          "uri": "https://eu.api.example.com/v3",
          "type": "constant"
        },
        {
          "uri": "https://ap.api.example.com/v3",
          "type": "constant"
        }
      ]
    }
  }
}

​
Example: Multi-Tenant SaaS

{
  "status": "finished",
  "result": {
    "infoAboutSchema": {
      "name": "SaaS Platform",
      "applicationVersion": "2024.2",
      "apiVersion": "v1",
      "apiType": ["REST"],
      "baseApiEndpoint": [
        {
          "uri": "https://{tenant}.platform.com/api/v1",
          "type": "dynamic"
        }
      ]
    }
  }
}

​
Example: SCIM API

{
  "status": "finished",
  "result": {
    "infoAboutSchema": {
      "name": "Enterprise Directory",
      "applicationVersion": "5.2.1",
      "apiVersion": "2.0",
      "apiType": ["SCIM", "REST"],
      "baseApiEndpoint": [
        {
          "uri": "https://directory.example.com/scim/v2",
          "type": "constant"
        }
      ]
    }
  }
}

​
Error Responses

​
status_code
number
HTTP status code
​
detail
string
Error message

​
Common Errors

404 Not Found - Session not found 
{
  "detail": "Session not found: 550e8400-e29b-41d4-a716-446655440000"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us