Bulk URL Checker Agent API

openapi: 3.2.0
info:
  title: Reception Desk Agent API
  description: API Gateway for URL Checker Engine
  version: 1.0.0
tags:
- name: agent-api
paths:
  /api/v2/jobs:
    post:
      tags:
      - agent-api
      summary: Submit Job
      description: 'Create a new URL-checking job from a list of URLs.


        Behavior:

        - URLs must include scheme (http:// or https://). Invalid URLs are

        silently dropped and counted in the response''s `invalid_urls_rejected`.

        - Duplicate URLs are deduplicated; `duplicates_removed` in response.

        - Hard cap: 100,000 URLs per job (same as the web UI; the shared

        MAX_RUN_PER_JOB). Accounts on a disposable mailbox get a 300-URL

        free allowance instead, and a 402 above it.

        - Credits: we deduct min(total_urls, balance). If the balance is

        less than total_urls the job creates in ''paused'' at the credit

        ceiling; the caller can add credits and poll status to see it

        resume on its own (same behavior as the web UI).


        Idempotency:

        - If the client sends an `Idempotency-Key` header, the response

        is cached for 24 hours. A retry with the same key returns the

        original response (same job_id, same credits_allocated) instead

        of creating a duplicate job. Different body + same key returns

        409 conflict. Convention: generate a UUIDv4 per logical

        request and reuse it on retries.'
      operationId: submit_job_api_v2_jobs_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitJobRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/jobs/wait:
    post:
      tags:
      - agent-api
      summary: Submit And Wait
      description: 'Submit URLs and block until the job finishes (or `wait_seconds` elapses).

        On completion, returns the job summary plus the full results list.

        On timeout, returns `timed_out=true` and partial results — the caller

        can finish the work asynchronously via `GET /jobs/{id}/results`.


        Best for small-to-medium URL lists (≤2,000 typical, hard ceiling

        enforced upstream at MAX_URLS_PER_JOB). For large jobs, use the

        submit + poll pattern: it''s resilient to proxy timeouts and

        serverless cold-starts.'
      operationId: submit_and_wait_api_v2_jobs_wait_post
      parameters:
      - name: wait_seconds
        in: query
        required: false
        schema:
          type: integer
          maximum: 900
          minimum: 1
          description: Max seconds to block waiting for completion. Default 60, cap 900.
          default: 60
          title: Wait Seconds
        description: Max seconds to block waiting for completion. Default 60, cap 900.
      - name: poll_interval
        in: query
        required: false
        schema:
          type: number
          maximum: 10.0
          minimum: 0.5
          description: Seconds between status polls while waiting. Default 2.
          default: 2.0
          title: Poll Interval
        description: Seconds between status polls while waiting. Default 2.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitJobRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Submit And Wait Api V2 Jobs Wait Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/jobs/{job_id}:
    get:
      tags:
      - agent-api
      summary: Get Job Status
      description: Current status of a job owned by the caller. 404 if not owned or missing.
      operationId: get_job_status_api_v2_jobs__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__api__v2__routes_jobs__JobStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - agent-api
      summary: Cancel Job
      description: 'Cancel a running job and refund unprocessed credits.


        2026-08-09: rewritten to cancel v2 jobs directly (was calling

        job-service /jobs/{id}/cancel which only handles v1 rows). Mirrors

        the v2-reception-desk /jobs/{id}/cancel logic (see

        services/v2-reception-desk/src/api/jobs.py:586) — cancels pending

        v2_url_items, bumps v2_jobs counters, refunds credits for URLs we

        didn''t execute. Leased URLs continue naturally.'
      operationId: cancel_job_api_v2_jobs__job_id__delete
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/jobs/{job_id}/results:
    get:
      tags:
      - agent-api
      summary: Get Job Results
      description: 'Paginated results for a job. Two modes:


        1. Offset/limit (default): `?limit=100&offset=200`. Simple but

        the page contents can shift if results change between calls

        (e.g., a new URL finishes checking). Fine for one-shot fetches.


        2. Cursor (recommended for full exports): omit `offset`, pass

        `cursor=` (and `limit=`). The response''s `next_cursor`

        field carries the cursor for the next page; null means the

        end of the stream. Pages are stable under concurrent writes.


        Ownership is checked before proxying to job-service. The underlying

        page size caps at 1000 so a single request is bounded.'
      operationId: get_job_results_api_v2_jobs__job_id__results_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Opaque cursor from a previous response's `next_cursor`. When set, results are returned in stable id-asc order and `offset` is ignored. Pagination ends when `next_cursor` is null in the response.
          title: Cursor
        description: Opaque cursor from a previous response's `next_cursor`. When set, results are returned in stable id-asc order and `offset` is ignored. Pagination ends when `next_cursor` is null in the response.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResultsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/usage:
    get:
      tags:
      - agent-api
      summary: Get Usage
      description: Current credit balance for the key owner.
      operationId: get_usage_api_v2_usage_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/verified-domains:
    get:
      tags:
      - agent-api
      summary: List Verified Domains V2
      description: 'Domains this key''s owner has proven ownership of.


        Verified domains are checked substantially faster. Exposed on the

        agent API so MCP / SDK callers can discover the feature — there is no

        UI in that context to stumble across it.


        Read-only. Verification itself stays interactive (it requires placing

        a DNS TXT record or a meta tag), so there is no create endpoint here.'
      operationId: list_verified_domains_v2_api_v2_verified_domains_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedDomainsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/webhooks/endpoints:
    post:
      tags:
      - agent-api
      summary: Create Endpoint
      description: 'Register a new webhook endpoint.


        Returns the endpoint metadata plus the signing_secret. Save the

        secret somewhere safe -- it''s only returned here. The receiving

        service must use it to verify incoming Bulkurlchecker-Signature

        headers (HMAC-SHA256 over `.`).'
      operationId: create_endpoint_api_v2_webhooks_endpoints_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndpointRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - agent-api
      summary: List Endpoints
      description: List all webhook endpoints owned by the caller, including revoked ones.
      operationId: list_endpoints_api_v2_webhooks_endpoints_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EndpointResponse'
                title: Response List Endpoints Api V2 Webhooks Endpoints Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/webhooks/endpoints/{endpoint_id}:
    get:
      tags:
      - agent-api
      summary: Get Endpoint
      operationId: get_endpoint_api_v2_webhooks_endpoints__endpoint_id__get
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - agent-api
      summary: Update Endpoint
      operationId: update_endpoint_api_v2_webhooks_endpoints__endpoint_id__patch
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEndpointRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - agent-api
      summary: Revoke Endpoint
      description: 'Soft-revoke the endpoint. Pending deliveries are dropped on the

        next worker poll. Delivery history stays for audit; create a new

        endpoint if you need a fresh secret.'
      operationId: revoke_endpoint_api_v2_webhooks_endpoints__endpoint_id__delete
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/audits:
    post:
      tags:
      - agent-api
      summary: Create Audit
      operationId: create_audit_api_v2_audits_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuditRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAuditResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UpdateEndpointRequest:
      properties:
        url:
          anyOf:
          - type: string
            maxLength: 2083
            minLength: 1
            format: uri
          - type: 'null'
          title: Url
        label:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Label
        events:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Events
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
      type: object
      title: UpdateEndpointRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VerifiedDomainsResponse:
      properties:
        verified_domains:
          items:
            $ref: '#/components/schemas/VerifiedDomainItem'
          type: array
          title: Verified Domains
        count:
          type: integer
          title: Count
      type: object
      required:
      - verified_domains
      - count
      title: VerifiedDomainsResponse
    CreateAuditRequest:
      properties:
        domain:
          type: string
          maxLength: 255
          title: Domain
          description: The domain to audit, e.g. 'https://example.com'. SSRF defense rejects private and loopback addresses.
        label:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Label
          description: Optional human-readable label for the audit job.
      type: object
      required:
      - domain
      title: CreateAuditRequest
    src__api__v2__routes_jobs__JobStatusResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        total_urls:
          type: integer
          title: Total Urls
        completed_urls:
          type: integer
          title: Completed Urls
        credits_allocated:
          type: integer
          title: Credits Allocated
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
      type: object
      required:
      - job_id
      - status
      - total_urls
      - completed_urls
      - credits_allocated
      title: JobStatusResponse
    SubmitJobRequest:
      properties:
        urls:
          items:
            type: string
          type: array
          minItems: 1
          title: Urls
          description: List of URLs to check. Each URL must include an explicit http:// or https:// scheme. Duplicates are removed.
        name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Name
          description: Optional human-readable label for this job. Reserved -- not yet persisted.
      type: object
      required:
      - urls
      title: SubmitJobRequest
    EndpointResponse:
      properties:
        id:
          type: string
          title: Id
        url:
          type: string
          title: Url
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        events:
          items:
            type: string
          type: array
          title: Events
        enabled:
          type: boolean
          title: Enabled
        created_at:
          type: string
          title: Created At
        revoked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked At
      type: object
      required:
      - id
      - url
      - events
      - enabled
      - created_at
      title: EndpointResponse
      description: Endpoint as visible to the client. Never includes signing_secret.
    CreateEndpointRequest:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
          description: Destination URL. Must be HTTPS in production (http:// allowed for localhost/loopback during dev).
        label:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Label
          description: Optional human-readable label, shown in the dashboard.
        events:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Events
          description: Optional event-type allowlist. Empty/omitted = subscribe to every supported event. Currently the only event is 'job.completed'.
      type: object
      required:
      - url
      title: CreateEndpointRequest
    CreateAuditResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        domain:
          type: string
          title: Domain
        audit_source:
          type: string
          title: Audit Source
        sitemap_url:
          type: string
          title: Sitemap Url
        total_urls:
          type: integer
          title: Total Urls
        credits_allocated:
          type: integer
          title: Credits Allocated
        status:
          type: string
          title: Status
      type: object
      required:
      - job_id
      - domain
      - audit_source
      - sitemap_url
      - total_urls
      - credits_allocated
      - status
      title: CreateAuditResponse
    JobResultsResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        total:
          type: integer
          title: Total
        offset:
          type: integer
          title: Offset
        limit:
          type: integer
          title: Limit
        results:
          items:
            $ref: '#/components/schemas/UrlResult'
          type: array
          title: Results
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
        reveal:
          anyOf:
          - type: object
          - type: 'null'
          title: Reveal
      type: object
      required:
      - job_id
      - total
      - offset
      - limit
      - results
      title: JobResultsResponse
    UsageResponse:
      properties:
        credit_balance:
          type: integer
          title: Credit Balance
      type: object
      required:
      - credit_balance
      title: UsageResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VerifiedDomainItem:
      properties:
        domain:
          type: string
          title: Domain
        verified_via:
          type: string
          title: Verified Via
        verified_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Verified At
        status:
          type: string
          title: Status
          default: associated
      type: object
      required:
      - domain
      - verified_via
      title: VerifiedDomainItem
    SubmitJobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
        total_urls:
          type: integer
          title: Total Urls
        credits_allocated:
          type: integer
          title: Credits Allocated
        duplicates_removed:
          type: integer
          title: Duplicates Removed
        invalid_urls_rejected:
          type: integer
          title: Invalid Urls Rejected
        unsupported_skipped:
          type: integer
          title: Unsupported Skipped
          default: 0
      type: object
      required:
      - job_id
      - status
      - total_urls
      - credits_allocated
      - duplicates_removed
      - invalid_urls_rejected
      title: SubmitJobResponse
    CreatedEndpointResponse:
      properties:
        id:
          type: string
          title: Id
        url:
          type: string
          title: Url
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        events:
          items:
            type: string
          type: array
          title: Events
        enabled:
          type: boolean
          title: Enabled
        created_at:
          type: string
          title: Created At
        revoked_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked At
        signing_secret:
          type: string
          title: Signing Secret
      type: object
      required:
      - id
      - url
      - events
      - enabled
      - created_at
      - signing_secret
      title: CreatedEndpointResponse
      description: 'Same as EndpointResponse but with the signing secret. Returned

        ONLY on POST so the user can copy it once.'
    UrlResult:
      properties:
        url:
          type: string
          title: Url
        status_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Status Code
        response_time:
          anyOf:
          - type: integer
          - type: 'null'
          title: Response Time
        final_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Final Url
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        is_soft_404:
          type: boolean
          title: Is Soft 404
          default: false
      type: object
      required:
      - url
      title: UrlResult