{
  "openapi": "3.1.0",
  "info": {
    "title": "Highnote API",
    "version": "2026-09-03",
    "summary": "HTTP transport for the Highnote GraphQL API — card issuing, acquiring, credit, and money movement.",
    "description": "Highnote exposes one GraphQL endpoint per environment. Every operation — queries, mutations, and schema introspection — is an HTTP POST of a JSON document to `/graphql`. This OpenAPI document describes that transport (authentication, request and response envelopes, error and rate-limit semantics) so tooling and agents can discover the API automatically; the operations themselves are defined by the GraphQL schema, which authenticated clients can introspect and which is published at https://docs.highnote.com/docs/api-reference/query.\n\nMachine-readable entry points for this site: `https://highnote.com/llms.txt` (site index for agents), `https://highnote.com/llms-full.txt`, `https://highnote.com/sitemap.xml`, and any page requested with `Accept: text/markdown` (or its `.md` sibling URL, e.g. `/pricing.md`).",
    "termsOfService": "https://highnote.com/agreements/terms",
    "contact": {
      "name": "Highnote",
      "url": "https://highnote.com/contact"
    },
    "license": {
      "name": "Highnote Terms of Service",
      "url": "https://highnote.com/agreements/terms"
    }
  },
  "externalDocs": {
    "description": "Highnote developer documentation",
    "url": "https://docs.highnote.com"
  },
  "servers": [
    {
      "url": "https://api.us.highnote.com",
      "description": "Live environment (United States)"
    },
    {
      "url": "https://api.us.test.highnote.com",
      "description": "Test environment (United States) — sandbox data, same schema"
    }
  ],
  "tags": [
    {
      "name": "GraphQL",
      "description": "The single GraphQL endpoint.",
      "externalDocs": {
        "description": "Using the Highnote API",
        "url": "https://docs.highnote.com/docs/developers/api/using-the-api"
      }
    }
  ],
  "security": [
    {
      "apiKeyBasic": []
    }
  ],
  "paths": {
    "/graphql": {
      "post": {
        "tags": ["GraphQL"],
        "operationId": "executeGraphQLOperation",
        "summary": "Execute a GraphQL query, mutation, or introspection request",
        "description": "Send the operation document as JSON. Mutations should carry an `IdempotencyKey` argument so a retried request cannot create a duplicate (see https://docs.highnote.com/docs/developers/api/idempotency). Validation and business-logic failures are returned *as data* in `UserError` types inside the mutation payload rather than in the top-level `errors` array; see https://docs.highnote.com/docs/developers/api/error-handling. Every response includes `extensions.requestId` — quote it when contacting support.",
        "externalDocs": {
          "description": "Introduction to GraphQL at Highnote",
          "url": "https://docs.highnote.com/docs/developers/api/intro-to-graphql"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GraphQLRequest"
              },
              "examples": {
                "ping": {
                  "summary": "Connectivity check",
                  "value": {
                    "query": "query PingPong { ping }"
                  }
                },
                "introspection": {
                  "summary": "Discover the schema",
                  "value": {
                    "query": "query Introspect { __schema { queryType { name } mutationType { name } types { name kind } } }"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation executed. Inspect `data`; a partially failed operation still returns 200 with an `errors` array alongside any resolvable `data`. Responses are `Content-Type: application/json`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GraphQLResponse"
                },
                "example": {
                  "data": {
                    "ping": "pong"
                  },
                  "extensions": {
                    "requestId": "4378192a-3529-928c-9894-5f815edd4f07",
                    "rateLimit": {
                      "asOf": "2024-03-15T18:29:36.090Z",
                      "count": {
                        "cost": 1,
                        "remaining": 199,
                        "limit": 200
                      },
                      "complexity": {
                        "cost": 10,
                        "remaining": 2490,
                        "limit": 2500
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The document could not be parsed or validated against the schema (wrong type, missing required field, unknown field). Fix the operation; do not retry unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GraphQLResponse"
                },
                "example": {
                  "data": null,
                  "errors": [
                    {
                      "message": "String cannot represent integer",
                      "locations": [
                        {
                          "line": 1,
                          "column": 6
                        }
                      ],
                      "errorPath": []
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credentials. Check that the `Authorization` header carries the base64-encoded API key for the environment you are calling (test keys are rejected by the live host and vice versa).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GraphQLResponse"
                },
                "example": {
                  "errors": [
                    {
                      "message": "Bad credentials. Please check your credentials and try again."
                    }
                  ],
                  "extensions": {
                    "requestId": "330c16c1-1301-9fca-a771-660cea5ac497"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: the per-key request-count or complexity budget is exhausted. Read `extensions.rateLimit` and retry with exponential backoff after the budget resets (https://docs.highnote.com/docs/developers/api/rate-limiting).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GraphQLResponse"
                },
                "example": {
                  "data": {},
                  "errors": [
                    {
                      "message": "Usage limit exceeded. More than x request points used in y seconds. See https://highnote.com/docs/developers/api/error-handling#rate-limit-errors for details on how to handle API rate limits."
                    }
                  ],
                  "extensions": {
                    "requestId": "4378192a-3529-928c-9894-5f815edd4f07",
                    "rateLimit": {
                      "asOf": "2024-03-15T18:29:36.090Z",
                      "count": {
                        "cost": 1,
                        "remaining": 0,
                        "limit": 200
                      },
                      "complexity": {
                        "remaining": 0,
                        "limit": 2500
                      }
                    }
                  }
                }
              }
            }
          },
          "5XX": {
            "description": "Transient server error. Retry with backoff; include the `requestId` from the body, if present, when contacting support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GraphQLResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic authentication with an API key created in the Highnote Dashboard. The credential is the API key base64-encoded on its own (`echo -n 'YOUR_API_KEY' | base64`) sent as `Authorization: Basic <encoded>`; no password is required. Keys are environment-specific. See https://docs.highnote.com/docs/developers/api/using-the-api#authorization."
      }
    },
    "schemas": {
      "GraphQLRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "description": "The GraphQL document: a query, a mutation, or an introspection query."
          },
          "variables": {
            "type": "object",
            "additionalProperties": true,
            "description": "Values for the variables declared in `query`."
          },
          "operationName": {
            "type": "string",
            "description": "Which operation to run when `query` defines more than one."
          }
        },
        "additionalProperties": false
      },
      "GraphQLResponse": {
        "type": "object",
        "properties": {
          "data": {
            "description": "The operation result, keyed by root field. `null` when the request failed before execution.",
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GraphQLError"
            },
            "description": "Request-level failures: syntax, validation, authentication, rate limiting. Business-rule failures are returned as `UserError` data instead."
          },
          "extensions": {
            "$ref": "#/components/schemas/ResponseExtensions"
          }
        }
      },
      "GraphQLError": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": {
            "type": "string"
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "line": {
                  "type": "integer"
                },
                "column": {
                  "type": "integer"
                }
              }
            }
          },
          "errorPath": {
            "type": "array",
            "items": {
              "type": ["string", "integer"]
            },
            "description": "Path to the field that failed, when applicable."
          }
        },
        "additionalProperties": true
      },
      "ResponseExtensions": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Unique identifier for this request. Log it; Highnote support uses it to trace the call."
          },
          "rateLimit": {
            "$ref": "#/components/schemas/RateLimit"
          }
        },
        "additionalProperties": true
      },
      "RateLimit": {
        "type": "object",
        "description": "Remaining request-count and complexity budget for the calling API key at `asOf`. On a 429 the `cost` fields are omitted.",
        "properties": {
          "asOf": {
            "type": "string",
            "format": "date-time"
          },
          "count": {
            "$ref": "#/components/schemas/RateLimitBucket"
          },
          "complexity": {
            "$ref": "#/components/schemas/RateLimitBucket"
          }
        },
        "additionalProperties": true
      },
      "RateLimitBucket": {
        "type": "object",
        "properties": {
          "cost": {
            "type": "integer",
            "description": "What this request consumed."
          },
          "remaining": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      }
    }
  }
}