GoPie Logo

OpenAPI Specification

OpenAPI/Swagger specification for Providence API

Providence provides a comprehensive OpenAPI 3.0 specification that describes all API endpoints, request/response schemas, and authentication methods.

Accessing the Specification

Live Documentation

Interactive API documentation is available at:

Download Specification

Download the OpenAPI specification in various formats:

# JSON format
curl https://api.providence.io/openapi.json -o providence-openapi.json

# YAML format
curl https://api.providence.io/openapi.yaml -o providence-openapi.yaml

Programmatic Access

// Fetch OpenAPI spec programmatically
const response = await fetch('https://api.providence.io/openapi.json');
const openApiSpec = await response.json();

console.log(`API Version: ${openApiSpec.info.version}`);
console.log(`Total Endpoints: ${Object.keys(openApiSpec.paths).length}`);

Specification Overview

openapi: 3.0.3
info:
  title: Providence API
  description: |
    Providence API enables natural language querying of databases and datasets.
    
    ## Authentication
    
    The API supports two authentication methods:
    - **API Key**: Use `Authorization: Bearer pvd_live_xxx` header
    - **JWT Token**: Use `Authorization: Bearer <jwt_token>` header
    
    ## Base URLs
    
    - Production: `https://api.providence.io`
    - Sandbox: `https://sandbox.api.providence.io`
    - EU Region: `https://eu.api.providence.io`
    
  version: 2.0.0
  contact:
    name: Providence Support
    email: [email protected]
    url: https://docs.providence.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.providence.io
    description: Production server
  - url: https://sandbox.api.providence.io
    description: Sandbox server
  - url: https://eu.api.providence.io
    description: EU region server

security:
  - ApiKeyAuth: []
  - BearerAuth: []

tags:
  - name: Projects
    description: Project management operations
  - name: Datasets
    description: Dataset management and operations
  - name: Queries
    description: Query execution and management
  - name: Organizations
    description: Organization and team management
  - name: Users
    description: User profile and settings
  - name: Auth
    description: Authentication endpoints

Authentication

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: |
        API Key authentication. Use keys starting with `pvd_live_` for production
        and `pvd_test_` for testing.
    
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication for user sessions
    
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.providence.io/oauth/authorize
          tokenUrl: https://auth.providence.io/oauth/token
          scopes:
            projects:read: Read project data
            projects:write: Create and modify projects
            datasets:read: Read dataset data
            datasets:write: Create and modify datasets
            queries:execute: Execute queries
            organizations:manage: Manage organizations

Common Schemas

components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: RESOURCE_NOT_FOUND
            message:
              type: string
              example: The requested resource was not found
            details:
              type: object
              additionalProperties: true
              example:
                resource_id: proj_123
                resource_type: project
    
    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - pages
      properties:
        page:
          type: integer
          minimum: 1
          example: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
          example: 20
        total:
          type: integer
          minimum: 0
          example: 156
        pages:
          type: integer
          minimum: 0
          example: 8
    
    Project:
      type: object
      required:
        - id
        - name
        - slug
        - organizationId
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          pattern: ^proj_[a-zA-Z0-9]+$
          example: proj_abc123def456
        name:
          type: string
          minLength: 1
          maxLength: 100
          example: Sales Analytics 2024
        slug:
          type: string
          pattern: ^[a-z0-9-]+$
          example: sales-analytics-2024
        description:
          type: string
          maxLength: 500
          example: Comprehensive sales data analysis
        organizationId:
          type: string
          pattern: ^org_[a-zA-Z0-9]+$
          example: org_xyz789
        visibility:
          type: string
          enum: [private, organization, public]
          default: private
        status:
          type: string
          enum: [active, archived]
          default: active
        tags:
          type: array
          items:
            type: string
          example: [sales, analytics, 2024]
        settings:
          $ref: '#/components/schemas/ProjectSettings'
        statistics:
          $ref: '#/components/schemas/ProjectStatistics'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

Example Endpoints

List Projects

paths:
  /api/v1/projects:
    get:
      tags:
        - Projects
      summary: List projects
      description: Get all projects accessible to the authenticated user
      operationId: listProjects
      parameters:
        - name: organizationId
          in: query
          description: Filter by organization ID
          schema:
            type: string
            pattern: ^org_[a-zA-Z0-9]+$
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: search
          in: query
          description: Search in project names and descriptions
          schema:
            type: string
        - name: status
          in: query
          description: Filter by status
          schema:
            type: string
            enum: [active, archived]
        - name: sort
          in: query
          description: Sort field
          schema:
            type: string
            enum: [created_at, updated_at, name]
            default: updated_at
        - name: order
          in: query
          description: Sort order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - projects
                  - pagination
                properties:
                  projects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                success:
                  value:
                    projects:
                      - id: proj_abc123def456
                        name: Sales Analytics 2024
                        slug: sales-analytics-2024
                        description: Comprehensive sales data analysis
                        organizationId: org_xyz789
                        visibility: private
                        status: active
                        createdAt: '2024-01-15T10:00:00Z'
                        updatedAt: '2025-01-20T14:30:00Z'
                    pagination:
                      page: 1
                      limit: 20
                      total: 42
                      pages: 3
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per hour
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix timestamp when limit resets

Execute Query

/api/v1/projects/{projectId}/queries/execute:
  post:
    tags:
      - Queries
    summary: Execute a query
    description: Execute a natural language or SQL query
    operationId: executeQuery
    parameters:
      - name: projectId
        in: path
        required: true
        description: Project ID
        schema:
          type: string
          pattern: ^proj_[a-zA-Z0-9]+$
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - query
            properties:
              query:
                type: string
                description: The query to execute
                example: What were the top 10 products by revenue last month?
              type:
                type: string
                enum: [natural_language, sql]
                default: natural_language
                description: Query type
              datasets:
                type: array
                items:
                  type: string
                  pattern: ^ds_[a-zA-Z0-9]+$
                description: Dataset IDs to query (optional)
              options:
                type: object
                properties:
                  limit:
                    type: integer
                    minimum: 1
                    maximum: 10000
                    default: 1000
                  timeoutSeconds:
                    type: integer
                    minimum: 1
                    maximum: 300
                    default: 30
                  explain:
                    type: boolean
                    default: false
                  cache:
                    type: boolean
                    default: true
    responses:
      '200':
        description: Query executed successfully
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryResult'
      '400':
        description: Invalid query
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'
      '408':
        description: Query timeout
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Error'

Code Generation

Using OpenAPI Generator

# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i https://api.providence.io/openapi.json \
  -g typescript-axios \
  -o ./generated/typescript-client

# Generate Python client
openapi-generator-cli generate \
  -i https://api.providence.io/openapi.json \
  -g python \
  -o ./generated/python-client

# Generate Go client
openapi-generator-cli generate \
  -i https://api.providence.io/openapi.json \
  -g go \
  -o ./generated/go-client

Using Swagger Codegen

# Download spec
curl https://api.providence.io/openapi.json -o providence-api.json

# Generate client
swagger-codegen generate \
  -i providence-api.json \
  -l typescript-angular \
  -o ./generated/angular-client

Custom Templates

Create custom templates for code generation:

{{! custom-api-client.mustache }}
import { Configuration } from './configuration';
import { {{classname}} } from './api';

export class ProvidenceClient {
  private config: Configuration;
  {{#apiInfo}}
  {{#apis}}
  {{#operations}}
  public {{classnameLowerCase}}: {{classname}};
  {{/operations}}
  {{/apis}}
  {{/apiInfo}}
  
  constructor(apiKey: string, baseUrl?: string) {
    this.config = new Configuration({
      apiKey: apiKey,
      basePath: baseUrl || 'https://api.providence.io'
    });
    
    {{#apiInfo}}
    {{#apis}}
    {{#operations}}
    this.{{classnameLowerCase}} = new {{classname}}(this.config);
    {{/operations}}
    {{/apis}}
    {{/apiInfo}}
  }
}

Validation

Validate Requests

import OpenAPIRequestValidator from 'openapi-request-validator';
import spec from './providence-openapi.json';

// Create validator for specific endpoint
const validator = new OpenAPIRequestValidator({
  parameters: spec.paths['/api/v1/projects/{projectId}/queries/execute'].post.parameters,
  requestBody: spec.paths['/api/v1/projects/{projectId}/queries/execute'].post.requestBody,
  componentSchemas: spec.components.schemas
});

// Validate request
const errors = validator.validateRequest({
  params: { projectId: 'proj_123' },
  body: {
    query: 'Show me sales data',
    type: 'natural_language'
  }
});

if (errors) {
  console.error('Validation errors:', errors);
}

Validate Responses

import OpenAPIResponseValidator from 'openapi-response-validator';

const responseValidator = new OpenAPIResponseValidator({
  responses: spec.paths['/api/v1/projects'].get.responses,
  componentSchemas: spec.components.schemas
});

const validationErrors = responseValidator.validateResponse(200, responseBody);

Mock Server

Using Prism

# Install Prism
npm install -g @stoplight/prism-cli

# Start mock server
prism mock https://api.providence.io/openapi.json

# Mock server will be available at http://localhost:4010

Using Postman

  1. Import OpenAPI spec into Postman
  2. Create mock server from collection
  3. Use mock server URL for testing
// Postman pre-request script
pm.environment.set('baseUrl', 
  pm.environment.get('useMock') === 'true' 
    ? 'https://mock.providence.io' 
    : 'https://api.providence.io'
);

Extensions

Providence API uses OpenAPI extensions for additional functionality:

# Rate limiting information
x-rate-limit:
  default: 100
  window: 3600
  scope: user

# Webhook events
x-webhooks:
  query.completed:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryCompletedEvent'

# Code samples
x-code-samples:
  - lang: curl
    source: |
      curl -X GET https://api.providence.io/api/v1/projects \
        -H "Authorization: Bearer pvd_live_xxx"
  - lang: python
    source: |
      import requests
      
      response = requests.get(
        'https://api.providence.io/api/v1/projects',
        headers={'Authorization': 'Bearer pvd_live_xxx'}
      )
  - lang: javascript
    source: |
      const response = await fetch('https://api.providence.io/api/v1/projects', {
        headers: {
          'Authorization': 'Bearer pvd_live_xxx'
        }
      });

Tools and Integrations

Postman Collection

Import the OpenAPI spec into Postman:

  1. Open Postman
  2. Click "Import" → "Link"
  3. Enter: https://api.providence.io/openapi.json
  4. Configure environment variables: 
    {
  "baseUrl": "https://api.providence.io",
  "apiKey": "pvd_live_your_api_key"
}

Insomnia

Import into Insomnia:

  1. Create new workspace
  2. Import → From URL
  3. Enter: https://api.providence.io/openapi.json
  4. Configure environment

API Documentation Tools

ReDoc

<!DOCTYPE html>
<html>
  <head>
    <title>Providence API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
  </head>
  <body>
    <redoc spec-url='https://api.providence.io/openapi.json'></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script>
  </body>
</html>

Swagger UI

<!DOCTYPE html>
<html>
  <head>
    <title>Providence API - Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
    <script>
      window.onload = function() {
        window.ui = SwaggerUIBundle({
          url: "https://api.providence.io/openapi.json",
          dom_id: '#swagger-ui',
          presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIBundle.SwaggerUIStandalonePreset
          ]
        });
      };
    </script>
  </body>
</html>

Best Practices

  1. Version Management: Always specify API version in requests
  2. Schema Validation: Validate requests/responses against OpenAPI spec
  3. Code Generation: Use official spec for generating clients
  4. Mock Development: Use mock servers for development
  5. Documentation: Keep OpenAPI spec as source of truth
  6. Breaking Changes: Follow semantic versioning for API changes

Support