octocrawl-dev API

openapi: 3.1.0
info:
  title: octocrawl-dev API
  version: '2026-10-30'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-30: 31 operation(s) read from 10 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; octocrawl-dev has published no machine-readable contract
    that the pipeline could find. Engine: anthropic.'
  x-evidence-tiers:
    code-example: 2
    documentation: 29
    pages-with-code: 3
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-30'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://octocrawl.dev/docs/reference
  - https://octocrawl.dev/docs/reference/index.md
  - https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
  - https://octocrawl.dev/docs/connect-mcp
  - https://octocrawl.dev/docs/scrape
  - https://octocrawl.dev/docs/limits
  - https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-19-h1-hosted-jobs-plan.md
  - https://github.com/77777R7/Octocrawl/blob/main/docs/json-extraction.md
  - https://github.com/77777R7/Octocrawl/blob/main/docs/access.md
  - https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-18-cloud-feature-plan.md
servers:
- url: https://api.octocrawl.dev
paths:
  /.well-known/mcp/server-card.json:
    get:
      operationId: get_well_known_mcp_server_card_json
      tags:
      - API
      summary: Smithery's server card listing the server's name, version, and authentication requirements.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/account/activity:
    get:
      operationId: get_api_account_activity
      tags:
      - Api
      summary: Retrieve the signed-in account's activity log and request history.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/account/run:
    post:
      operationId: post_api_account_run
      tags:
      - Api
      summary: Run a scrape or map for the signed-in account without requiring an API key.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/capability:
    get:
      operationId: get_api_capability
      tags:
      - Api
      summary: Reads the planned route and limitation for a given URL using a query parameter.
      x-source: https://octocrawl.dev/docs/limits
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
        description: A public URL (encoded) to check for preview capability
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCapabilityResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_capability
      tags:
      - Api
      summary: Reads the planned route and limitation for a given URL using a JSON body with the URL.
      x-source: https://octocrawl.dev/docs/limits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiCapabilityRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiCapabilityResponse'
      x-evidence:
        kind: documentation
  /api/quota:
    get:
      operationId: get_api_quota
      tags:
      - Api
      summary: Reads the preview quota remaining for the current visitor without spending anything.
      x-source: https://octocrawl.dev/docs/limits
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiQuotaResponse'
      x-evidence:
        kind: documentation
  /crawl:
    post:
      operationId: post_crawl
      tags:
      - Crawl
      summary: Submit a hosted crawl task with multiple URLs to run asynchronously in the cloud.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-18-cloud-feature-plan.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCrawlRequest'
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCrawlResponse'
      x-evidence:
        kind: documentation
  /health:
    get:
      operationId: get_health
      tags:
      - Health
      summary: Health check endpoint.
      x-source: https://octocrawl.dev/docs/reference
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHealthResponse'
      x-evidence:
        kind: documentation
  /internal/jobs/{id}/slice:
    post:
      operationId: post_internal_jobs_id_slice
      tags:
      - Internal
      summary: Execute one slice of a hosted job.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-19-h1-hosted-jobs-plan.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostInternalJobsIdSliceRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostInternalJobsIdSliceResponse'
      x-evidence:
        kind: documentation
  /mcp-oauth:
    post:
      operationId: post_mcp_oauth
      tags:
      - Mcp Oauth
      summary: 'OAuth sign-in endpoint where the client sends Authorization: Bearer oca_… token.'
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/batches:
    post:
      operationId: post_v1_batches
      tags:
      - Batches
      summary: Scrape an explicit URL array.
      x-source: https://octocrawl.dev/docs/reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1BatchesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1BatchesResponse'
      x-evidence:
        kind: documentation
  /v1/batches/{id}:
    get:
      operationId: get_v1_batches_id
      tags:
      - Batches
      summary: Retrieve a batch job's status and results by its ID.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/batches/{id}/cancel:
    post:
      operationId: post_v1_batches_id_cancel
      tags:
      - Batches
      summary: Cancel a running batch job.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-19-h1-hosted-jobs-plan.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/batches/{id}/handoff:
    post:
      operationId: post_v1_batches_id_handoff
      tags:
      - Batches
      summary: Hand off a stopped batch page to the user's Chrome to get through a check.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/access.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1BatchesIdHandoffResponse'
      x-evidence:
        kind: documentation
  /v1/batches/{id}/items:
    get:
      operationId: get_v1_batches_id_items
      tags:
      - Batches
      summary: Get paginated outcomes from a batch.
      x-source: https://octocrawl.dev/docs/reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1BatchesIdItemsResponse'
      x-evidence:
        kind: documentation
  /v1/crawl:
    post:
      operationId: post_v1_crawl
      tags:
      - Crawl
      summary: Crawl by following links.
      x-source: https://octocrawl.dev/docs/reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CrawlRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1CrawlResponse'
      x-evidence:
        kind: documentation
  /v1/crawl/{id}:
    get:
      operationId: get_v1_crawl_id
      tags:
      - Crawl
      summary: Get a crawl by ID.
      x-source: https://octocrawl.dev/docs/reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CrawlIdResponse'
      x-evidence:
        kind: documentation
  /v1/crawl/{id}/cancel:
    post:
      operationId: post_v1_crawl_id_cancel
      tags:
      - Crawl
      summary: Cancel a running crawl job.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-19-h1-hosted-jobs-plan.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/crawl/{id}/pages:
    get:
      operationId: get_v1_crawl_id_pages
      tags:
      - Crawl
      summary: Paginate through the pages of a crawl job.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-19-h1-hosted-jobs-plan.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor in the format slice:line
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1CrawlIdPagesResponse'
      x-evidence:
        kind: documentation
  /v1/jobs:
    get:
      operationId: get_v1_jobs
      tags:
      - Jobs
      summary: List job tools.
      x-source: https://octocrawl.dev/docs/reference
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1JobsResponse'
      x-evidence:
        kind: documentation
  /v1/jobs/{id}/export:
    get:
      operationId: get_v1_jobs_id_export
      tags:
      - Jobs
      summary: Get a signed URL to download the complete export of a finished job.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/launch/2026-10-19-h1-hosted-jobs-plan.md
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1JobsIdExportResponse'
      x-evidence:
        kind: documentation
  /v1/logins:
    get:
      operationId: get_v1_logins
      tags:
      - Logins
      summary: List the saved logins.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/access.md
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1LoginsResponse'
      x-evidence:
        kind: documentation
  /v1/logins/{site}:
    delete:
      operationId: delete_v1_logins_site
      tags:
      - Logins
      summary: Forget a saved login for a site.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/access.md
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/logins/import:
    post:
      operationId: post_v1_logins_import
      tags:
      - Logins
      summary: Import a login for a site from Chrome's saved credentials.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/access.md
      parameters:
      - name: site
        in: query
        required: true
        schema:
          type: string
        description: Domain or page URL of the site to import login for
      - name: approveTimeoutMs
        in: query
        required: false
        schema:
          type: integer
        description: How long to wait for Chrome's Allow, 10 s to 10 min, default 2 min
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1LoginsImportRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1LoginsImportResponse'
      x-evidence:
        kind: documentation
  /v1/map:
    post:
      operationId: post_v1_map
      tags:
      - Map
      summary: Map a site's URLs.
      x-source: https://octocrawl.dev/docs/reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1MapRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1MapResponse'
      x-evidence:
        kind: documentation
  /v1/maps/{id}:
    get:
      operationId: get_v1_maps_id
      tags:
      - Maps
      summary: Get a map result by ID.
      x-source: https://octocrawl.dev/docs/reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1MapsIdResponse'
      x-evidence:
        kind: documentation
  /v1/projects:
    patch:
      operationId: patch_v1_projects
      tags:
      - Projects
      summary: PATCH /v1/projects
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X PATCH -H \" authorization: Bearer $T \" -H \" x-goog-user-project: $W2L_PROJECT_ID \" -H ' content-type: application/json\
          \ '  \" https://firestore.googleapis.com/v1/projects/ $W2L_PROJECT_ID /databases/(default)/documents/hostedConfig/jobs?updateMask.fieldPaths=allowedUids\
          \ \"  -d ' {\"fields\":{\"allowedUids\":{\"arrayValue\":{\"values\":[{\"stringValue\":\"<uid>\"}]}}}} ' \n ` ` ` Off, a start answers\
          \ 503"
  /v1/read:
    post:
      operationId: post_v1_read
      tags:
      - Read
      summary: Read a page with the hosted browser lane and return its result.
      x-source: https://github.com/77777R7/Octocrawl/blob/main/docs/hosted-api.md
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ReadRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/scrape:
    get:
      operationId: get_v1_scrape
      tags:
      - Scrape
      summary: GET /v1/scrape
      x-source: https://octocrawl.dev/docs/connect-mcp
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H 'authorization: Bearer oc_…' https://api.octocrawl.dev/v1/scrape . \n Clients can also sign in instead of sending a\
          \ key . \n Sign in instead of a key \n https://mcp.octocrawl.dev/mcp-oauth is the same server for clients that sign in with OAuth instead\
          \ of sending a key. The client opens an Octocrawl page where you sign in and choose Authorize. Its calls then spend your account’s credits,\
          \ as a "
    post:
      operationId: post_v1_scrape
      tags:
      - Scrape
      summary: Scrape one URL.
      x-source: https://octocrawl.dev/docs/reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ScrapeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1ScrapeResponse'
      x-evidence:
        kind: documentation
  /v1/scrapes/{id}:
    get:
      operationId: get_v1_scrapes_id
      tags:
      - Scrapes
      summary: Get a scrape result by ID.
      x-source: https://octocrawl.dev/docs/reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1ScrapesIdResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiCapabilityResponse:
      type: object
      properties:
        route:
          type: string
          description: Planned route for the given URL
        limitation:
          type: string
          description: Any limitation affecting this URL
    PostApiCapabilityRequest:
      type: object
      properties:
        url:
          type: string
          description: A public URL to check for preview capability
      required:
      - url
    PostApiCapabilityResponse:
      type: object
      properties:
        route:
          type: string
          description: Planned route for the given URL
        limitation:
          type: string
          description: Any limitation affecting this URL
    GetApiQuotaResponse:
      type: object
      properties:
        quota_remaining:
          type: integer
          description: Number of previews remaining for this visitor in the current UTC day
        site_quota_remaining:
          type: integer
          description: Number of previews remaining site-wide in the current UTC day
    PostCrawlRequest:
      type: object
      properties:
        urls:
          type: array
          description: List of URLs to crawl
        maxCredits:
          type: integer
          description: Maximum credits to spend on this task
        idempotencyKey:
          type: string
          description: Idempotency key to prevent duplicate submissions
      required:
      - urls
    PostCrawlResponse:
      type: object
      properties:
        jobId:
          type: string
          description: The task job ID for tracking
        status:
          type: string
          description: Initial job status
    GetHealthResponse:
      type: object
      properties:
        status:
          type: string
    PostInternalJobsIdSliceRequest:
      type: object
      properties:
        generation:
          type: string
          description: Generation number for this slice to ensure consistency
      required:
      - generation
    PostInternalJobsIdSliceResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code (200 for success or discarded old slice, 503 for lease occupied, 200 for terminal state)
    PostV1BatchesRequest:
      type: object
      properties:
        urls:
          type: string
      required:
      - urls
    PostV1BatchesResponse:
      type: object
      properties:
        batchId:
          type: string
    PostV1BatchesIdHandoffResponse:
      type: object
      properties:
        page:
          type: object
          description: The page after handoff
    GetV1BatchesIdItemsResponse:
      type: object
      properties:
        items:
          type: string
        cursor:
          type: string
    PostV1CrawlRequest:
      type: object
      properties:
        url:
          type: string
      required:
      - url
    PostV1CrawlResponse:
      type: object
      properties:
        crawlId:
          type: string
    GetV1CrawlIdResponse:
      type: object
      properties:
        crawlId:
          type: string
        pages:
          type: string
    GetV1CrawlIdPagesResponse:
      type: object
      properties:
        pages:
          type: array
          description: Array of page results
        nextCursor:
          type: string
          description: Cursor for the next page of results
    GetV1JobsResponse:
      type: object
      properties:
        jobs:
          type: string
    GetV1JobsIdExportResponse:
      type: object
      properties:
        url:
          type: string
          description: Signed URL to export.jsonl.gz, valid for 15 minutes
    GetV1LoginsResponse:
      type: object
      properties:
        logins:
          type: array
          description: List of saved logins
    PostV1LoginsImportRequest:
      type: object
      properties:
        site:
          type: string
          description: Domain or page URL
        approveTimeoutMs:
          type: integer
          description: Approval timeout in milliseconds
      required:
      - site
    PostV1LoginsImportResponse:
      type: object
      properties:
        domain:
          type: string
        savedAt:
          type: string
        cookieCount:
          type: integer
        localStorage:
          type: object
          description: Object with origins and itemCount, or null
        localStorageRead:
          type: boolean
        sessionSha256:
          type: string
    PostV1MapRequest:
      type: object
      properties:
        url:
          type: string
      required:
      - url
    PostV1MapResponse:
      type: object
      properties:
        urls:
          type: string
    GetV1MapsIdResponse:
      type: object
      properties:
        urls:
          type: string
    PostV1ReadRequest:
      type: object
      properties:
        url:
          type: string
        options:
          type: object
        deadlineAt:
          type: string
      required:
      - url
    PostV1ScrapeRequest:
      type: object
      properties:
        url:
          type: string
        format:
          type: string
        maxFileBytes:
          type: string
        actions:
          type: string
        skipTlsVerification:
          type: string
        includePaths:
          type: string
      required:
      - url
    PostV1ScrapeResponse:
      type: object
      properties:
        scrapeId:
          type: string
        metadata:
          type: string
        markdown:
          type: string
        json:
          type: string
        evidenceRecord:
          type: string
    GetV1ScrapesIdResponse:
      type: object
      properties:
        scrapeId:
          type: string
        metadata:
          type: string
        markdown:
          type: string
        json:
          type: string
        evidenceRecord:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: API
- name: Api
- name: Batches
- name: Crawl
- name: Health
- name: Internal
- name: Jobs
- name: Logins
- name: Map
- name: Maps
- name: Mcp Oauth
- name: Projects
- name: Read
- name: Scrape
- name: Scrapes