Agentik Discover API

openapi: 3.2.0
info:
  title: Agentik agent Discover API
  version: 0.1.0
  summary: 'Pay-per-call tools for AI agents: one API key, one prepaid balance, many providers.'
  description: 'Three primitives: discover (free, public), inspect (free, public), run (API key, billed per call). Prices are the providers'' own, without markup; a platform fee applies when a human tops up the balance. A run normally reserves its maximum. Tools with pricing.costMode=actual reserve an estimate and bill the exact provider receipt without a per-call cap; additional usage may be debited. Keys with optional spending caps cannot run these tools. Unused funds are released; uncertain consumption stays reserved for reconciliation, including after a connection error. Separate executions are charged separately; idempotency keys replay an existing execution. Some tools create a live resource (browser session, agent run): the run stays RUNNING and is settled when the resource ends. MCP (Streamable HTTP) is served at https://ai.agentik.cc/mcp with the same catalog and billing; it authorizes through OAuth 2.1 (metadata at https://ai.agentik.cc/.well-known/oauth-protected-resource/mcp) or the API key. https://ai.agentik.cc/mcp/public serves discover and inspect without credentials. Inspect each tool for its complete input schema. This document covers customer integration only.'
servers:
- url: https://api.agentik.cc
security: []
tags:
- name: Discover
paths:
  /v1/agent-info:
    get:
      tags:
      - Discover
      summary: Customer capabilities, endpoints, catalog counts and billing rules
      responses:
        '200':
          description: Authoritative deployment facts. billing.status is unavailable when payment readiness could not be checked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentInfo'
        '405':
          description: METHOD_NOT_ALLOWED; use the method in the Allow response header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Allow:
              schema:
                type: string
              description: Supported methods
        '503':
          description: Temporarily unavailable. Read error.hint; do not create a duplicate execution after an uncertain outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getAgentInfo
  /connect.md:
    get:
      tags:
      - Discover
      summary: Public MCP installation guide for agents and humans
      responses:
        '200':
          description: Markdown setup guide for this API environment
          content:
            text/markdown:
              schema:
                type: string
        '503':
          description: Guide deployment configuration is unavailable
          content:
            text/markdown:
              schema:
                type: string
      operationId: get_connect_md
  /v1/discover:
    post:
      tags:
      - Discover
      summary: Search the catalog in natural language
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: What you need, e.g. 'weather forecast for a city'
                limit:
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 5
                sort:
                  type: string
                  enum:
                  - relevance
                  - price
                  - latency
                  - reliability
                  default: relevance
                max_price_usd:
                  type: number
                  exclusiveMinimum: 0
                  description: Only tools whose typical call costs at most this; excludes tools with uncapped actual-cost billing
      responses:
        '200':
          description: Ranked candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverResponse'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Reset:
              schema:
                type: integer
                minimum: 0
              description: Unix seconds when capacity next becomes available in this sliding window
        '400':
          description: Missing query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Reset:
              schema:
                type: integer
                minimum: 0
              description: Unix seconds when capacity next becomes available in this sliding window
        '405':
          description: METHOD_NOT_ALLOWED; use the method in the Allow response header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Allow:
              schema:
                type: string
              description: Supported methods
            X-RateLimit-Limit:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Reset:
              schema:
                type: integer
                minimum: 0
              description: Unix seconds when capacity next becomes available in this sliding window
        '429':
          description: RATE_LIMITED; wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait when a retry time is known
            X-RateLimit-Limit:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Reset:
              schema:
                type: integer
                minimum: 0
              description: Unix seconds when capacity next becomes available in this sliding window
        '503':
          description: Temporarily unavailable. Read error.hint; do not create a duplicate execution after an uncertain outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Current caller's rate window; omitted when unavailable or limited by shared provider capacity
            X-RateLimit-Reset:
              schema:
                type: integer
                minimum: 0
              description: Unix seconds when capacity next becomes available in this sliding window
      operationId: discoverTools
  /v1/tools:
    get:
      tags:
      - Discover
      summary: 'Customer catalog: tools available now'
      responses:
        '200':
          description: Every customer tool that can run now, with price and input schema. Temporarily unavailable tools are omitted and return automatically.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tool'
        '405':
          description: METHOD_NOT_ALLOWED; use the method in the Allow response header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Allow:
              schema:
                type: string
              description: Supported methods
        '503':
          description: Temporarily unavailable. Read error.hint; do not create a duplicate execution after an uncertain outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: listTools
  /v1/tools/reliability:
    get:
      tags:
      - Discover
      summary: Reliability of each tool over the last 7 days
      description: Finished calls only, for tools available now with at least min_runs calls; the rate is rounded to the percent and the median to 10 ms. A tool without enough calls is absent, not unreliable.
      responses:
        '200':
          description: Per-tool completed share, call count and median duration
          content:
            application/json:
              schema:
                type: object
                required:
                - window_days
                - min_runs
                - tools
                properties:
                  window_days:
                    type: integer
                  min_runs:
                    type: integer
                  tools:
                    type: object
                    additionalProperties:
                      type: object
                      required:
                      - runs_7d
                      - success_rate_7d
                      - p50_ms
                      properties:
                        runs_7d:
                          type: integer
                        success_rate_7d:
                          type: number
                          minimum: 0
                          maximum: 1
                        p50_ms:
                          type:
                          - integer
                          - 'null'
        '405':
          description: METHOD_NOT_ALLOWED; use the method in the Allow response header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Allow:
              schema:
                type: string
              description: Supported methods
        '429':
          description: RATE_LIMITED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'UNAVAILABLE: the run history cannot be read right now'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: get_v1_tools_reliability
  /v1/tools/{provider}/{tool}:
    get:
      tags:
      - Discover
      summary: Inspect one available tool (input schema, price, license)
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
      - name: tool
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Tool spec
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '404':
          description: TOOL_NOT_FOUND (unknown tool) or TOOL_NOT_ACTIVE (temporarily unavailable; use discover to choose an alternative)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: METHOD_NOT_ALLOWED; use the method in the Allow response header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Allow:
              schema:
                type: string
              description: Supported methods
        '503':
          description: Temporarily unavailable. Read error.hint; do not create a duplicate execution after an uncertain outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: inspectTool
  /mcp/public:
    post:
      tags:
      - Discover
      summary: 'Public MCP endpoint: discover_tools and inspect_tool without credentials'
      description: Only discover_tools and inspect_tool are listed here. Connect to /mcp with OAuth or an API key for run_tool, run_and_show and get_run.
      security: []
      responses:
        '200':
          description: JSON-RPC response
      operationId: post_mcp_public
components:
  schemas:
    AgentInfo:
      type: object
      required:
      - version
      - name
      - environment
      - endpoints
      - billing
      - catalog
      - operations
      - authentication
      - limits
      properties:
        version:
          const: '1'
        name:
          const: Agentik
        environment:
          enum:
          - preview
          - standard
        endpoints:
          type: object
          required:
          - api
          - mcp
          - public_mcp
          - openapi
          - installation
          properties:
            api:
              type: string
              format: uri
            mcp:
              type: string
              format: uri
            public_mcp:
              type: string
              format: uri
            openapi:
              type: string
              format: uri
            installation:
              type: string
              format: uri
        billing:
          type: object
          required:
          - status
          - currency
          - payments_enabled
          - payment_mode
          - auto_recharge_available
          - topup_fee_model
          - topup_fee_rate
          - topup_fee_min_usd
          - topup_min_usd
          - free_runs_per_day_unfunded
          - free_runs_per_day_funded
          properties:
            status:
              enum:
              - ready
              - unavailable
            currency:
              const: USD
            payments_enabled:
              type: boolean
            payment_mode:
              enum:
              - 'off'
              - test
              - live
            auto_recharge_available:
              type: boolean
            topup_fee_model:
              const: added
            topup_fee_rate:
              type: number
              minimum: 0
            topup_fee_min_usd:
              type: number
              minimum: 0
            topup_min_usd:
              type: number
              minimum: 0
            free_runs_per_day_unfunded:
              type: number
              minimum: 0
            free_runs_per_day_funded:
              type: number
              minimum: 0
        catalog:
          type: object
          description: Counts of the customer catalog, which only lists tools available now; unavailable is kept for compatibility and is always 0.
          properties:
            total:
              type: integer
              minimum: 0
            available:
              type: integer
              minimum: 0
            unavailable:
              type: integer
              minimum: 0
            providers:
              type: integer
              minimum: 0
        operations:
          type: object
          properties:
            public:
              type: array
              items:
                type: string
            authenticated:
              type: array
              items:
                type: string
        authentication:
          type: object
          properties:
            rest:
              type: array
              items:
                type: string
            mcp:
              type: array
              items:
                type: string
            public_mcp:
              const: none
        limits:
          type: object
          properties:
            run_requests_per_minute:
              type: integer
              minimum: 1
            discovery_requests_per_minute:
              type: integer
              minimum: 1
            discovery_max_results:
              type: integer
              minimum: 1
    Tool:
      type: object
      required:
      - id
      - provider
      - name
      - description
      - category
      - tags
      - access
      - pricing
      - inputSchema
      - status
      - available
      - auth_required
      properties:
        id:
          type: string
          examples:
          - open-meteo/forecast
        provider:
          type: string
        operator_only:
          type: boolean
          description: Provider-account maintenance operation; execution restricted to the configured operator workspace.
        name:
          type: string
        description:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        access:
          type: string
          enum:
          - open
          - platform_key
          - byok
          - partner
          - connection
        pricing:
          $ref: '#/components/schemas/Pricing'
        license:
          type: string
        attribution:
          type: string
        docsUrl:
          type: string
        inputSchema:
          type: object
          description: JSON Schema (draft 7) of the run input
        status:
          type: string
          enum:
          - active
          description: 'Always active: customer surfaces only list tools that can run now'
        available:
          type: boolean
          const: true
        auth_required:
          type: string
          enum:
          - none
          - platform
          - byok
          - partner
          - connection
        connection:
          type: object
          description: Present for automatically provisioned workspace access. Human platform consent uses the URL and notice returned by getmcpads/connect-source; Agentik owner/admin session is required to open it.
          properties:
            provider:
              type: string
              enum:
              - getmcpads
            name:
              type: string
            how:
              type: string
        settlement:
          type: string
          enum:
          - deferred
          description: Present when the final price is known only when the upstream resource ends
        upstream:
          type: string
          enum:
          - http
          - mcp
          description: Whether the tool is served by an HTTP API or a third-party MCP server
        starred:
          type: boolean
          description: 'Recommended by Agentik ("Starred by Agentik"). Editorial only: it changes neither price nor ranking.'
    Pricing:
      oneOf:
      - type: object
        required:
        - model
        - amountUsd
        properties:
          model:
            const: per_call
          amountUsd:
            type: number
          multipliers:
            type: array
            items:
              type: object
      - type: object
        required:
        - model
        - amountUsd
        - unitsPath
        - maxUnits
        properties:
          model:
            const: per_unit
          amountUsd:
            type: number
          unitsPath:
            type: string
          maxUnits:
            type: number
      - type: object
        required:
        - model
        - amountUsd
        - maxMinutes
        properties:
          model:
            const: per_minute
          amountUsd:
            type: number
          maxMinutes:
            type: number
      - type: object
        required:
        - model
        - costPath
        - maxUsdDefault
        - maxUsdCap
        properties:
          model:
            const: reported
          costPath:
            type: string
          costMode:
            const: actual
            description: Reservation is an estimate; bill the exact receipt without a per-call cap.
          reservationBasis:
            type: string
          maxUsdDefault:
            type: number
          maxUsdCap:
            type: number
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            hint:
              type: string
            request_id:
              type: string
            retry_after_ms:
              type: number
              minimum: 0
            documentation:
              type: string
              format: uri
          additionalProperties: true
    DiscoverResponse:
      type: object
      properties:
        query:
          type: string
        results:
          type: array
          items:
            type: object
            properties:
              tool_id:
                type: string
              name:
                type: string
              description:
                type: string
              price:
                $ref: '#/components/schemas/Pricing'
              price_estimate_usd:
                type: number
                description: Typical cost of one call, comparable across pricing models
              status:
                type: string
                enum:
                - active
                description: Discovery only returns tools available now
              available:
                type: boolean
                const: true
              score:
                type: number
              reliability_7d:
                type: number
                description: Share of successful runs over the last 7 days, when runs exist
              p50_ms:
                type: integer
                description: Median latency over the last 7 days, when runs exist
              runs_7d:
                type: integer
              why:
                type: array
                items:
                  type: string
                description: Why this result ranks where it does
            additionalProperties: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: trk_...
      description: Workspace API key
    oauth:
      type: oauth2
      description: 'OAuth for MCP clients: PKCE S256, dynamic client registration or client ID metadata documents, refresh token rotation. With agent onboarding enabled, a verified account approves a dedicated execution key; otherwise the legacy authorization page accepts an existing workspace key. Tokens inherit the key policy.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.agentik.cc/oauth/authorize
          tokenUrl: https://api.agentik.cc/oauth/token
          refreshUrl: https://api.agentik.cc/oauth/token
          scopes:
            run: Discover, inspect and run tools, paid from the workspace balance within the key's caps
externalDocs:
  url: https://api.agentik.cc/connect.md
  description: Connection guide
x-agentik-billing:
  payments_enabled: true
  topup_fee_model: added
  topup_fee_rate: 0.055
  topup_fee_min_usd: 0.8
  topup_min_usd: 5
  free_runs_per_day_unfunded: 50
  free_runs_per_day_funded: 1000