Obsidyan Logo
    API v1

    Obsidyan API

    A REST API and MCP server for your applications, claims, sections, deadlines, office actions and quality reviews, plus AI drafting, claim options and prior art search.

    Base URL

    All API requests should be made to

    https://obsidyan.ai/api/v1

    API Playground

    Test the API directly from your browser. Try the status endpoint to verify connectivity.

    GET
    /v1/status

    Check API health and status

    Note: Authentication is required for most endpoints. Get your API key from the settings page.

    Response
    // Click 'Test Endpoint' to see the response

    Authentication

    The Obsidyan API uses API keys for authentication. Include your API key in the Authorization header of all requests.

    API Key Authentication

    Bearer token in Authorization header

    Header
    Authorization: Bearer your_api_key
    Keep keys secure
    Never expose API keys in client-side code
    Rotate regularly
    Revoke old keys and create new ones periodically
    Scoped permissions
    Create keys with minimal required permissions

    API Key Scopes

    Create keys in Settings. They start with oip_ and are shown once.

    read

    Read your data. New keys have this scope by default.

    write

    Also create, update and delete, and run AI features.

    admin

    Everything write can do.

    API Endpoints

    Successful responses return { success: true, data, meta }, where meta holds the version, a timestamp and a request_id. Every request runs as the key's owner, so it only sees that account's data. Requests other than GET need a key with the write scope.

    GET
    /v1/patents
    ?limit
    POST
    /v1/patents
    body
    GET
    /v1/patents/{id}
    PUT
    /v1/patents/{id}
    body
    DELETE
    /v1/patents/{id}
    GET
    /v1/claims
    ?patent_id
    POST
    /v1/claims
    body
    PUT
    /v1/claims/{id}
    body
    DELETE
    /v1/claims/{id}
    GET
    /v1/sections
    ?patent_id
    PUT
    /v1/sections
    body
    POST
    /v1/prior-art/search
    body
    POST
    /v1/prior-art/analyze
    body
    GET
    /v1/filings
    POST
    /v1/filings
    body
    GET
    /v1/filings/{id}/status
    GET
    /v1/drawings
    ?patent_id
    POST
    /v1/drawings/generate
    body
    GET
    /v1/office-actions
    GET
    /v1/office-actions/{id}
    POST
    /v1/office-actions/{id}/analyze
    POST
    /v1/office-actions/{id}/respond
    body
    GET
    /v1/examiner-stats
    ?name*
    GET
    /v1/deadlines
    ?status
    GET
    /v1/quality-reviews
    ?patent_id
    GET
    /v1/quality-reviews/{id}
    POST
    /v1/quality-reviews/run
    body
    POST
    /v1/quality-reviews
    body
    GET
    /v1/documents
    ?patent_id
    DELETE
    /v1/documents/{id}
    GET
    /v1/analytics/portfolio
    GET
    /v1/analytics/trends
    ?months
    POST
    /v1/ai/draft
    body
    POST
    /v1/ai/claim-options
    body
    POST
    /v1/ai/chat
    body
    GET
    /v1/credits/balance
    GET
    /v1/credits/transactions
    ?limit
    GET
    /v1/organizations
    POST
    /v1/organizations
    body
    GET
    /v1/organizations/{id}
    PUT
    /v1/organizations/{id}
    body
    GET
    /v1/organizations/{id}/members
    GET
    /v1/workspaces
    ?organization_id*
    POST
    /v1/workspaces
    body
    GET
    /v1/notifications
    ?limit
    PUT
    /v1/notifications/{id}
    POST
    /v1/notifications/read-all
    GET
    /v1/inventions
    ?limit
    POST
    /v1/inventions
    body
    GET
    /v1/inventions/{id}
    PUT
    /v1/inventions/{id}
    body
    DELETE
    /v1/inventions/{id}
    GET
    /v1/status

    Code Examples

    The API is plain HTTP and JSON, so any HTTP client works. There are no official SDKs yet.

    example.py
    import requests

API_URL = "https://obsidyan.ai/api/v1"
HEADERS = {"Authorization": "Bearer your_api_key"}

# List your patent applications
patents = requests.get(f"{API_URL}/patents", headers=HEADERS).json()["data"]["items"]

# Create a new application (needs a key with the write scope)
patent = requests.post(
    f"{API_URL}/patents",
    headers=HEADERS,
    json={
        "title": "Adaptive Battery Thermal Management System",
        "description": "A system that adjusts coolant flow from cell temperature readings...",
        "technology_area": "Energy storage",
        "filing_type": "provisional",
    },
).json()["data"]

# Save a section, then run the draft checks on the saved sections (free, no AI)
requests.put(
    f"{API_URL}/sections",
    headers=HEADERS,
    json={
        "patent_id": patent["id"],
        "section_type": "abstract",
        "content": "A thermal management system for a battery pack...",
    },
)
review = requests.post(
    f"{API_URL}/quality-reviews/run",
    headers=HEADERS,
    json={"patent_id": patent["id"]},
).json()["data"]

    Rate Limiting

    Each API key can make 100 requests per minute. Going over returns a 429 until the window resets.

    AI endpoints and MCP tools spend the key owner's credits at the prices on the Pricing page, only when the work succeeds, and return a 402 if the balance is too low. They need a key with the write scope. The first draft on an application costs 2,400 credits and covers every section of it, whether it's drafted in the app or through the API, for up to 100 runs. Claim options are free once the application is drafted. Quality checks and examiner statistics don't use AI or credits.

    AI endpoints return a 503 when they aren't available. GET /v1/status reports this as services.ai: "operational" or "unavailable".

    Rate Limit Headers

    Every API response includes rate limit information

    X-RateLimit-Limit

    Maximum requests allowed in the current window

    X-RateLimit-Remaining

    Requests remaining in the current window

    X-RateLimit-Reset

    Unix timestamp when the rate limit resets

    Error Handling

    The API uses conventional HTTP response codes. Error bodies carry a machine-readable code and type, a message, and the request_id to quote if you contact us.

    400
    Bad Request
    A required field is missing or a value is invalid
    401
    Unauthorized
    Invalid or missing API key
    402
    Payment Required
    Not enough credits, or claim options asked for before the application is drafted
    403
    Forbidden
    The key lacks the write scope, or you don't have access to this resource
    404
    Not Found
    Resource or endpoint does not exist
    405
    Method Not Allowed
    The endpoint doesn't accept this HTTP method
    409
    Conflict
    A charge for this is still in progress, or the review is locked
    429
    Too Many Requests
    Rate limit or per-application draft limit reached
    500
    Internal Server Error
    Server-side error occurred
    502
    Bad Gateway
    An upstream service, such as the AI provider or USPTO, failed
    503
    Service Unavailable
    AI endpoints, or a service they depend on, aren't available right now (code ai_unavailable; GET /v1/status shows when AI is on). /v1/examiner-stats returns service_unavailable when USPTO is down
    Error Response Example
    {
  "success": false,
  "error": {
    "code": "missing_field",
    "message": "The 'title' field is required",
    "param": "title",
    "type": "validation_error",
    "doc_url": "https://obsidyan.ai/api#errors"
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-11-07T12:00:00.000Z",
    "request_id": "req_..."
  }
}

    Versioning

    The current version is v1. The version is part of the URL, as in /api/v1/patents.

    Ready to Get Started?

    Create an API key in Settings and start with GET /v1/status.

    Get Your API KeyBrowse Endpoints

    MCP Server

    Connect AI agents to Obsidyan via the Model Context Protocol

    Live

    What is MCP?

    The Model Context Protocol (MCP) is an open standard that lets AI agents like Claude, Cursor, and Windsurf interact with external tools and data sources in a structured way.

    Our MCP server exposes 27 tools: applications, disclosures, prior art, drafting, claim options, draft checks, office actions, examiner statistics, filings, deadlines, drawings and more.

    Available Tools

    list_patent_applications
    get_patent_application
    create_patent_application
    update_patent_application
    list_invention_disclosures
    get_invention_disclosure
    create_invention_disclosure
    search_prior_art
    list_prior_art_searches
    list_drafting_sections
    generate_draft_section
    propose_claim_options
    check_draft
    list_office_actions
    analyze_office_action
    generate_office_action_response
    get_examiner_stats
    list_filing_records
    list_filing_deadlines
    list_documents
    list_quality_reviews
    chat_with_patent_assistant
    list_notifications
    mark_notification_read
    get_portfolio_summary
    generate_patent_drawing
    get_credit_balance

    Tools that create or change data need a key with the write scope. The AI tools (prior art search, drafting, drawings, office action analysis and responses, chat) charge credits from the key owner's balance and are available when GET /v1/status reports AI as operational. Claim options are free once an application is drafted; check_draft and get_examiner_stats use no AI and no credits.

    Connect to the MCP Server

    Add this configuration to your AI agent or MCP client

    {
  "mcpServers": {
    "obsidyan": {
      "url": "https://obsidyan.ai/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
    Replace YOUR_API_KEY with an API key from Settings. It only sees that account's data.

    Test with MCP Inspector

    npx @modelcontextprotocol/inspector

    Use the MCP Inspector to browse available tools, test requests, and validate responses interactively.