{
  "openapi": "3.0.3",
  "info": {
    "title": "Moca Network API",
    "description": "Server-to-server API for credential issuance and partner operations on the Moca Network.",
    "version": "1.0.0",
    "contact": {
      "name": "Moca Network",
      "url": "https://moca.network"
    }
  },
  "servers": [
    {
      "url": "https://api.sandbox.mocachain.org/v1",
      "description": "Sandbox"
    },
    {
      "url": "https://mocachain-mainnet.api.air3.com/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "partnerJwt": []
    }
  ],
  "paths": {
    "/catalog/schemas": {
      "get": {
        "operationId": "listSchemas",
        "summary": "Browse schemas",
        "description": "Returns a paginated list of credential schemas with their credential count and number of distinct issuers (providers). Only schemas marked as discoverable and enabled are included. Results are sortable by `created_at`, `credential_count`, `provider_count`, or `title` (default `created_at`).",
        "tags": [
          "Catalog"
        ],
        "security": [],
        "servers": [
          {
            "url": "https://credential-testnet.api.sandbox.air3.com",
            "description": "Credential API sandbox (catalog)"
          }
        ],
        "x-mint": {
          "content": "<Warning>\n**Pilot API** \u2014 Available on **Sandbox only** at this stage. Endpoint is under active development and may change without notice. Not yet available in production.\n</Warning>"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/SortBy"
          },
          {
            "$ref": "#/components/parameters/SortOrder"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of schemas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogApiResponse"
                },
                "example": {
                  "code": 80000000,
                  "msg": "success",
                  "data": {
                    "current": 1,
                    "pages": 5,
                    "size": 10,
                    "total": 47,
                    "records": [
                      {
                        "schemaId": "sch_01HX",
                        "title": "KYC Identity",
                        "description": "Basic identity verification schema",
                        "credentialCount": 5,
                        "providerCount": 3
                      }
                    ]
                  },
                  "timestamp": 1772530828000
                }
              }
            }
          }
        }
      }
    },
    "/catalog/schemas/{id}": {
      "get": {
        "operationId": "getSchemaDetail",
        "summary": "Schema detail",
        "description": "Returns a single schema together with every discoverable credential built on it. Each credential includes issuer info and traction metrics (holder count, issuance count, and demand count \u2014 the number of verification programs that accept it).",
        "tags": [
          "Catalog"
        ],
        "security": [],
        "servers": [
          {
            "url": "https://credential-testnet.api.sandbox.air3.com",
            "description": "Credential API sandbox (catalog)"
          }
        ],
        "x-mint": {
          "content": "<Warning>\n**Pilot API** \u2014 Available on **Sandbox only** at this stage. Endpoint is under active development and may change without notice. Not yet available in production.\n</Warning>"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Schema ID.",
            "schema": {
              "type": "string"
            },
            "example": "sch_01HX"
          }
        ],
        "responses": {
          "200": {
            "description": "Schema with credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogApiResponse"
                },
                "example": {
                  "code": 80000000,
                  "msg": "success",
                  "data": {
                    "schemaId": "sch_01HX",
                    "title": "KYC Identity",
                    "description": "Basic identity verification schema",
                    "credentials": [
                      {
                        "credentialId": "c21s70g0i54sn0023172Cv",
                        "name": "Age Verification",
                        "category": "identity",
                        "issuer": {
                          "issuerId": "iss_01",
                          "name": "Acme Corp"
                        },
                        "traction": {
                          "holderCount": 120,
                          "issuanceCount": 200,
                          "demandCount": 50
                        },
                        "createdAt": "2026-01-15T10:30:00Z"
                      }
                    ]
                  },
                  "timestamp": 1772530828000
                }
              }
            }
          },
          "404": {
            "description": "Schema not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": 404,
                  "message": "Schema not found"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "Page number (starts from 1).",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Results per page (max 100).",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        }
      },
      "SortBy": {
        "name": "sortBy",
        "in": "query",
        "required": false,
        "description": "Field to sort by.",
        "schema": {
          "type": "string"
        }
      },
      "SortOrder": {
        "name": "sortOrder",
        "in": "query",
        "required": false,
        "description": "Sort direction.",
        "schema": {
          "type": "string",
          "enum": [
            "ASC",
            "DESC"
          ],
          "default": "DESC"
        }
      }
    },
    "securitySchemes": {
      "partnerJwt": {
        "type": "apiKey",
        "in": "header",
        "name": "x-partner-auth",
        "description": "A signed Partner JWT containing `partnerId`, `email`, `scope`, and `exp` claims. See [Partner Authentication](/airkit/usage/partner-authentication) for setup."
      }
    },
    "schemas": {
      "CatalogApiResponse": {
        "type": "object",
        "description": "Standard API response envelope used by all Catalog endpoints.",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Response code. `80000000` indicates success.",
            "example": 80000000
          },
          "msg": {
            "type": "string",
            "description": "Human-readable status message.",
            "example": "success"
          },
          "data": {
            "description": "Response payload. Shape varies per endpoint."
          },
          "timestamp": {
            "type": "integer",
            "description": "UNIX timestamp in milliseconds.",
            "example": 1772530828000
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "integer",
            "description": "HTTP status code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description."
          }
        }
      }
    }
  }
}