Menu

OpenAPI Import

Convert OpenAPI specifications to paso declarations.

Generate a usepaso.yaml declaration from an existing OpenAPI spec. File or URL.

usepaso init --from-openapi ./openapi.json
usepaso init --from-openapi https://api.example.com/openapi.json

What Gets Generated

The import process extracts:

  • API name and version from info section
  • Base URL from servers[0].url
  • Capabilities from each path + method combination
  • Inputs from path parameters, query parameters, and request body
  • Descriptions from operation summaries and descriptions

Example output:

name: petstore-api
version: "1.0.0"
base_url: https://api.petstore.com/v1
auth:
  type: bearer

capabilities:
  - name: list_pets
    description: List all pets
    method: GET
    path: /pets
    permission: read
    inputs:
      - name: limit
        type: number
        description: How many items to return at one time
      - name: status
        type: string
        description: Filter by status

  - name: create_pet
    description: Create a new pet
    method: POST
    path: /pets
    permission: write
    inputs:
      - name: name
        type: string
        required: true
      - name: species
        type: string
        required: true

Curate Your Declaration

The auto-generated declaration is a starting point. You’ll typically customize it.

Remove Capabilities

Delete capabilities you don’t want to expose:

capabilities:
  - name: list_pets
    # ...

  # DELETE THIS SECTION if you don't want to expose create_pet
  # - name: create_pet
  #   # ...

Adjust Permissions

Set permission tiers based on risk:

  - name: delete_pet
    description: Delete a pet
    method: DELETE
    path: /pets/{id}
    permission: admin  # require admin approval
    consent_required: true

Add Constraints

Limit API usage with constraints:

  - name: list_pets
    description: List all pets
    method: GET
    path: /pets
    permission: read
    constraints:
      rate_limit: 10  # calls per minute
      max_items: 100

Add Forbidden Values

Prevent access to sensitive endpoints:

forbidden:
  paths:
    - /admin/*
    - /settings/billing
  methods:
    - DELETE

Complete Example

Here’s a curated Petstore API declaration:

name: petstore-api
version: "1.0.0"
base_url: https://api.petstore.com/v1
auth:
  type: bearer
  env_var: PETSTORE_API_KEY

capabilities:
  - name: list_pets
    description: List all pets in the store
    method: GET
    path: /pets
    permission: read
    constraints:
      rate_limit: 10

  - name: get_pet
    description: Get details for a specific pet
    method: GET
    path: /pets/{id}
    permission: read
    inputs:
      - name: id
        type: string
        required: true

  - name: create_pet
    description: Create a new pet listing
    method: POST
    path: /pets
    permission: write
    consent_required: true
    inputs:
      - name: name
        type: string
        required: true
      - name: species
        type: string
        required: true
        enum:
          - dog
          - cat
          - bird

  # DELETE operations removed — not exposing this via MCP

Validate after import

Always validate after importing:

usepaso validate

The generated declaration is a starting point. Review it, remove what you don’t need, and set appropriate permissions before serving.

Your OpenAPI spec is now a paso declaration.

Review it, set permissions, and serve.

Next, you might want to: