Skip to content

Interactive API Documentation

Our service generates interactive API documentation that allows you to explore and test endpoints directly from your browser. This guide covers some pointers for using it.

Accessing the Documentation

The interactive spec is here.

Understanding the Interface

Endpoint Overview

The spec groups endpoints by version or specific use cases. Each endpoint displays:

  • HTTP Method: GET, POST, PUT, DELETE, etc. (color-coded)
  • Path: The endpoint URL with any path parameters
  • Summary: A description of what the endpoint does and some important assumptions!

When you expand an endpoint, you'll see:

  • Parameters: Path parameters, query parameters, headers, and request body schema
  • Responses: Possible response codes with example response bodies
  • Example Values: Sample request/response payloads
  • Models: Schema definitions for complex objects

Working with Authentication

Most endpoints require authentication:

  1. Look for the "Authorize" button at the top of the page
  2. Click it to open the authentication dialog
  3. Enter your API key into the text field.
  4. Click "Authorize" to save
  5. Click "Close" to return to the documentation

Once authorized, all subsequent requests will include your authentication credentials automatically.

To log out, click "Authorize" again and use the "Logout" button for each security scheme.

Testing Endpoints

Making a Request

  1. Expand the endpoint you want to test
  2. Click "Try it out" button in the top-right of the endpoint section
  3. Fill in parameters:
  4. Path parameters appear as editable fields in the URL
  5. Query parameters appear as separate input fields
  6. Request body appears as an editable JSON object
  7. Click "Execute" to send the request

Reading the Response

After executing, you'll see:

  • Curl command: The exact curl command that was executed (useful for debugging or scripting)
  • Request URL: The full URL that was called
  • Response code: HTTP status code (200, 404, 500, etc.)
  • Response body: The actual JSON response from the server
  • Response headers: HTTP headers returned by the server

Tips and Best Practices

Editing Request Bodies

  • The default example value is often a good starting point
  • Click inside the request body field to edit the JSON directly
  • The interface validates JSON syntax as you type
  • Use the "Schema" tab to see required vs optional fields

Common Status Codes

  • 200 OK: Request succeeded
  • 201 Created: Resource was created successfully
  • 400 Bad Request: Invalid request (check your parameters)
  • 401 Unauthorized: Authentication required or failed
  • 403 Forbidden: Authenticated but not authorized for this resource
  • 404 Not Found: Endpoint or resource doesn't exist
  • 422 Unprocessable Entity: Validation error (check the response body for details)
  • 50x Internal Server Error: Server-side error (check logs)

Copying Requests

The documentation shows the exact curl command for each request. You can:

  • Copy the curl command to use in scripts or terminals
  • Convert it to other languages using tools like Postman or HTTPie
  • Use it as a reference for implementing API clients

Troubleshooting

"Authorization header is missing"

Make sure you've clicked the "Authorize" button and entered valid credentials before executing the request.

"422 Unprocessable Entity"

Your request body or parameters don't match the expected schema. Check:

  • All required fields are provided
  • Field types match (e.g., don't send a string for an integer field)
  • Values meet validation constraints (e.g., min/max length)
  • The response body will detail exactly which fields are invalid