⚠️Blast API (blastapi.io) ends Oct 31. Migrate to Dwellir and skip Alchemy's expensive compute units.
Switch Today →
Skip to main content

spec

Overview#

Retrieve the complete OpenAPI 3.0 specification for the Aptos REST API. This machine-readable document describes all available endpoints, request/response schemas, parameters, and error codes, enabling automated client generation and API exploration.

Endpoint#

GET /v1/spec

Request#

Path Parameters#

None.

Query Parameters#

None.

Request Body#

None.

Response#

Success Response (200)#

Returns a complete OpenAPI 3.0 specification document in JSON or YAML format (depending on Accept header):

{
  "openapi": "3.0.0",
  "info": {
    "title": "Aptos REST API",
    "version": "1.0.0"
  },
  "paths": {
    "/accounts/{address}": {...},
    "/transactions": {...}
  },
  "components": {
    "schemas": {...}
  }
}

The specification includes complete type definitions for all Move-related structures, transaction payloads, and response formats.

Code Examples#

curl -X GET https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/spec \
  -H "Accept: application/json"

Save specification to file:

curl -X GET https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/spec \
  -H "Accept: application/json" \
  -o aptos-openapi.json

Use Cases#

The OpenAPI specification enables various development workflows:

  1. Client SDK Generation: Generate type-safe API clients in any language using tools like OpenAPI Generator, Swagger Codegen, or language-specific generators. This eliminates manual API integration work and reduces errors.

  2. API Documentation: Import the spec into API documentation tools like Swagger UI, Redoc, or Postman to create interactive documentation with request/response examples and try-it-out functionality.

  3. Contract Testing: Use the specification to generate contract tests that validate API responses match expected schemas, catching breaking changes early.

  4. Mock Server Creation: Generate mock API servers for frontend development and testing without depending on live blockchain infrastructure.

  5. IDE Integration: Import specifications into REST clients (Insomnia, Postman) or IDE plugins (JetBrains HTTP Client, VSCode REST Client) for autocomplete and validation.

  6. API Change Tracking: Compare specifications across versions to identify breaking changes, deprecated endpoints, or new functionality in API updates.

Best Practices#

Version Pinning: The specification matches the API version of the node you're querying. For production applications, pin to a specific specification version and test thoroughly before upgrading.

Client Generation: When generating clients, configure the generator to handle Aptos-specific patterns like string-encoded large numbers (u64, u128) and 0x-prefixed addresses.

Schema Validation: Use the schemas from the specification to validate responses client-side, catching unexpected API changes or data corruption early.

Type Customization: Many OpenAPI generators support custom templates. Customize generated code to integrate with your existing type systems or add blockchain-specific validations.

Caching: The specification is relatively static. Cache it locally during development rather than fetching on every build. Update when you detect API version changes.

Format Selection: Request JSON format (default) for programmatic use. YAML format is more human-readable for manual review but requires appropriate Accept header.

Performance Considerations#

The specification document is large (typically 500KB-2MB) and rarely changes. Download once and cache locally for client generation and development purposes.

This endpoint doesn't touch blockchain state - it serves a static or infrequently-updated document describing the API surface. Response times are typically under 100ms, primarily limited by document transfer time.

Avoid fetching the specification at application runtime. Instead, generate clients during build time and ship compiled code to production.

Integration with Development Tools#

OpenAPI Generator:

openapi-generator generate \
  -i https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/spec \
  -g typescript-fetch \
  -o ./generated/aptos-client

Swagger UI:

const ui = SwaggerUI({
  url: "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/spec",
  dom_id: '#swagger-ui'
});

Postman Import: Download the spec and import directly into Postman to create a complete request collection with pre-configured endpoints and parameters.

  • Aptos TypeScript SDK uses this specification as basis for type definitions
  • Official Aptos OpenAPI spec repository on GitHub
  • OpenAPI 3.0 specification documentation at swagger.io