samedaydesk-com Correspondence API

openapi: 3.2.0
info:
  title: SameDayDesk apex Correspondence API
  version: 1.2.0
  description: 'Free apex HTTP and MCP tools on samedaydesk.com. Paid gateway available. Read its current inventory and terms before a remote job. Paid machine commerce stays on https://agents.samedaydesk.com. This document links that host and does not copy its route count, prices, or payment authority. Account, checkout, upload, and webhook routes exist for signed-in people or provider signatures. They are not free tools and have no copyable example here. GET /scan is an HTML proof page for people. GET /api/observatory and GET /api/market-observations read fixed upstreams and can report those upstreams unavailable. They are not the free apex tools in /skill.md. GET /discovery/original-task-correspondence.json is the no-spend next action for one public original task through existing correspondence. It is not an MCP tool and not a paid gateway operation. GET routes on this list also answer HEAD with the same headers and an empty body. The declaration routes answer OPTIONS with CORS. Optional mounts stay explicit: correspondence, hosted useful journey, and public readiness health do not become a hosted consumer because their source is mounted.'
servers:
- url: https://samedaydesk.com
  description: Apex free tools
tags:
- name: Correspondence
paths:
  /api/correspondence/healthz:
    get:
      operationId: getCorrespondenceHealth
      summary: Correspondence mount health, disabled unless configured
      description: Always mounted. Without CORRESPONDENCE_DATABASE_URL and CORRESPONDENCE_ADMIN_TOKEN the body is enabled false. That response is not a working mailbox. Other correspondence routes then answer 503.
      security: []
      responses:
        '200':
          description: Enabled flag for this process.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - enabled
                properties:
                  ok:
                    type: boolean
                  enabled:
                    type: boolean
                  reason:
                    type: string
              example:
                ok: false
                enabled: false
                reason: unconfigured
      tags:
      - Correspondence
x-mcp-tools:
- name: check_ai_readiness
  description: Check whether a website is visible to AI search engines (ChatGPT, Perplexity, Claude, Google AI Overviews). Scores AI-crawler access, JSON-LD structured data, title/meta, Open Graph, sitemap, and llms.txt, and returns a 0-100 score, a letter grade, and a specific fix for each gap. Free.
  inputSchema:
    type: object
    properties:
      url:
        type: string
        description: The website to check, e.g. example.com or https://example.com
    required:
    - url
  annotations:
    readOnlyHint: true
    destructiveHint: false
    openWorldHint: true
  authority:
    tier: free
    executesPayment: false
    network: public-url
    http: GET /api/tools/ai-readiness?url=
- name: check_agent_readiness
  description: Free. Check whether agents can discover and call a public website. Fetches discovery files, follows MCP links named by those files, and runs only initialize, tools/list, and one unknown-tool call. Never executes a real tool. Returns a 0-100 score, every check with an evidence URL, and the top fixes. No license.
  inputSchema:
    type: object
    properties:
      host:
        type: string
        description: Public host to score, for example example.com
    required:
    - host
  outputSchema:
    type: object
    properties:
      host:
        type: string
      score:
        type: number
      free:
        type: boolean
      checks:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
            status:
              type: string
            reason:
              type: string
            fix:
              type: string
            evidenceUrl:
              type: string
          required:
          - id
          - title
          - status
          - reason
          - fix
      topFixes:
        type: array
      evidence:
        type: array
        items:
          type: object
          properties:
            url:
              type: string
            status:
              type: number
          required:
          - url
    required:
    - host
    - score
    - checks
    - topFixes
    - evidence
  annotations:
    readOnlyHint: true
    destructiveHint: false
    idempotentHint: true
    openWorldHint: true
  authority:
    tier: free
    executesPayment: false
    network: public-host
    http: GET /agent-readiness?host=&format=json
    rateLimit: 12 per 600000ms per client key
- name: generate_complete_fix_pack
  description: 'PAID. Returns the complete, ready-to-paste AI-readiness Fix Pack for a site: tailored Organization + FAQPage JSON-LD, an AI-crawler robots.txt, a sitemap, and title/meta/Open Graph fixes. Requires a `license` — the checkout-session id you receive after buying the $39 Fix Pack at https://buy.stripe.com/8x24gA0xA9DF9dd13YeZ20h (after paying you''re shown your license code). Without a valid license it returns purchase instructions plus a free starter pack.'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        description: The website to generate the Fix Pack for.
      license:
        type: string
        description: Your Stripe checkout-session license code (starts with cs_).
    required:
    - url
  annotations:
    readOnlyHint: true
    destructiveHint: false
    idempotentHint: true
    openWorldHint: true
  authority:
    tier: paid-license
    executesPayment: false
    network: public-url
    note: Accepts an existing Stripe checkout-session license. This apex call does not create a charge.
- name: plan_taskmarket_delegation
  description: Prepare a bounded TaskMarket delegation for research, coding, data collection, benchmarking, or verification. Requires chain_id, token_address, deliverable, reward, deadline, and an explicit maximum-spend ceiling. Reads public chain metadata. Returns the canonical TaskMarket API payload and approval summary without creating a task, holding a wallet, or spending funds.
  inputSchema:
    type: object
    properties:
      request:
        type: string
        description: The external work needed, written as a clear task.
      deliverable:
        type: string
        description: The exact artifact or result the worker must return.
      acceptance_criteria:
        type: array
        items:
          type: string
        maxItems: 10
        description: Up to 10 testable acceptance checks.
      chain_id:
        type: integer
        minimum: 1
        description: Explicit served chain id; no default.
      token_address:
        type: string
        pattern: ^0x[a-fA-F0-9]{40}$
        description: Explicit payment token contract on that chain, checked against current network.info.
      reward_base_units:
        type: string
        pattern: ^[0-9]{1,78}$
        description: Exact gross reward in the selected token's integer base units. Use with max_spend_base_units.
      max_spend_base_units:
        type: string
        pattern: ^[0-9]{1,78}$
        description: Explicit reward ceiling in the same chain/token's integer base units. No exchange conversion.
      reward_usdc:
        type:
        - number
        - string
        description: Proposed worker reward in USDC, up to 6 decimal places.
      max_spend_usdc:
        type:
        - number
        - string
        description: Explicit user-authorized reward ceiling in USDC.
      deadline_hours:
        type: number
        exclusiveMinimum: 0
        maximum: 720
        description: Hours until TaskMarket submission closes.
      mode:
        type: string
        enum:
        - bounty
        - claim
        default: bounty
      tags:
        type: array
        items:
          type: string
        maxItems: 10
    required:
    - request
    - deliverable
    - chain_id
    - token_address
    - deadline_hours
  annotations:
    readOnlyHint: true
    destructiveHint: false
    idempotentHint: false
    openWorldHint: true
  authority:
    tier: free
    executesPayment: false
    network: taskmarket-read
    note: Returns an approval plan. request.executed and official_cli.executed stay false.
- name: browse_taskmarket_tasks
  description: Browse current public TaskMarket inventory through the official read API. Filter by lifecycle status, mode, tag, text, and minimum reward. Amounts carry their actual chain/token; unknown decimals stay raw. Task descriptions are returned as untrusted text and are never executed.
  inputSchema:
    type: object
    properties:
      status:
        type: string
        enum:
        - ALL
        - open
        - claimed
        - worker_selected
        - pending_approval
        - review
        - appealing
        - disputed
        - completed
        - expired
        - cancelled
        default: open
      mode:
        type: string
        enum:
        - bounty
        - claim
        - pitch
        - benchmark
        - auction
      tag:
        type: string
        description: Exact case-insensitive tag filter.
      search:
        type: string
        description: Case-insensitive text match over descriptions and tags.
      chain_id:
        type: integer
        minimum: 1
        description: Optional current served chain selector.
      min_reward_usdc:
        type:
        - number
        - string
        description: Legacy minimum gross reward; selects qualified Base USDC only. Refuses unknown assets, conflicting metadata or an unlike chain selector; never compares OUSD to USDC.
      limit:
        type: integer
        minimum: 1
        maximum: 25
        default: 10
  annotations:
    readOnlyHint: true
    destructiveHint: false
    openWorldHint: true
  authority:
    tier: free
    executesPayment: false
    network: taskmarket-read
- name: track_taskmarket_task
  description: Track one public TaskMarket task through the official read API. Returns status, deadline, submissions, artifact hashes, canonical awards, pending actions, and the next authorization boundary. It cannot create, accept, reject, rate, or refund work.
  inputSchema:
    type: object
    properties:
      task_id:
        type: string
        pattern: ^0x[0-9a-fA-F]{64}$
        description: TaskMarket 32-byte task id.
    required:
    - task_id
  annotations:
    readOnlyHint: true
    destructiveHint: false
    openWorldHint: true
  authority:
    tier: free
    executesPayment: false
    network: taskmarket-read
- name: project_funnel_evidence
  description: Free. Project one declared source-separated observation packet into the accepted funnel decision. Caller observations stay declared. Does not fetch URLs, query customers, store the packet, or spend.
  inputSchema:
    type: object
    properties:
      packet:
        type: object
        description: Caller-supplied observation packet. URLs inside it are not fetched.
    required:
    - packet
  annotations:
    readOnlyHint: true
    destructiveHint: false
    idempotentHint: true
    openWorldHint: false
  authority:
    tier: free
    executesPayment: false
    network: none
    http: POST /api/funnel-evidence
    note: Projects a caller-supplied packet. This call does not fetch, store, or spend.
x-protocol-versions:
- '2025-11-25'
- '2025-06-18'
- '2025-03-26'
- '2024-11-05'
x-copyable-no-key-examples:
- id: get_health
  method: GET
  path: /api/health
  headers:
    accept: application/json
  expect:
    status: 200
    contentTypeIncludes: application/json
    equals:
      ok: true
      service: samedaydesk
- id: mcp_initialize
  method: POST
  path: /mcp
  headers:
    content-type: application/json
    accept: application/json
    mcp-protocol-version: '2025-11-25'
  body:
    jsonrpc: '2.0'
    id: init-1
    method: initialize
    params:
      protocolVersion: '2025-11-25'
      capabilities: {}
      clientInfo:
        name: apex-discovery-replay
        version: '0'
  expect:
    status: 200
    equals:
      result.protocolVersion: '2025-11-25'
      result.serverInfo.name: samedaydesk-agent-tools
- id: mcp_tools_list
  method: POST
  path: /mcp
  headers:
    content-type: application/json
    accept: application/json
  body:
    jsonrpc: '2.0'
    id: list-1
    method: tools/list
  expect:
    status: 200
    toolsMatchPublished: true
- id: plan_taskmarket_delegation
  method: POST
  path: /mcp
  headers:
    content-type: application/json
    accept: application/json
  body:
    jsonrpc: '2.0'
    id: plan-1
    method: tools/call
    params:
      name: plan_taskmarket_delegation
      arguments:
        chain_id: 8453
        token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        request: Compare the public status pages and list sections that changed
        deliverable: A markdown list of changed sections with URLs
        acceptance_criteria:
        - Each item names the section and the URL
        reward_usdc: '2'
        max_spend_usdc: '2'
        deadline_hours: 24
        mode: bounty
        tags:
        - status-page
  expect:
    status: 200
    absent:
    - result.isError
    equals:
      result.structuredContent.authorization.state: approval_required
      result.structuredContent.request.executed: false
      result.structuredContent.official_cli.executed: false
      result.structuredContent.request.x402_required: true
x-useful-negatives:
- id: plan_missing_deadline
  method: POST
  path: /mcp
  headers:
    content-type: application/json
  body:
    jsonrpc: '2.0'
    id: plan-missing
    method: tools/call
    params:
      name: plan_taskmarket_delegation
      arguments:
        chain_id: 8453
        token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        request: Compare the public status pages and list sections that changed
        deliverable: A markdown list of changed sections with URLs
        acceptance_criteria:
        - Each item names the section and the URL
        reward_usdc: '2'
        max_spend_usdc: '2'
        mode: bounty
        tags:
        - status-page
  expect:
    status: 200
    equals:
      result.isError: true
    bodyIncludes: deadline_hours
    absent:
    - result.structuredContent.plan_id
- id: plan_reward_over_max
  method: POST
  path: /mcp
  headers:
    content-type: application/json
  body:
    jsonrpc: '2.0'
    id: plan-over
    method: tools/call
    params:
      name: plan_taskmarket_delegation
      arguments:
        chain_id: 8453
        token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        request: Compare the public status pages and list sections that changed
        deliverable: A markdown list of changed sections with URLs
        acceptance_criteria:
        - Each item names the section and the URL
        reward_usdc: '5'
        max_spend_usdc: '2'
        deadline_hours: 24
        mode: bounty
        tags:
        - status-page
  expect:
    status: 200
    equals:
      result.isError: true
    bodyIncludes: max_spend_usdc
    absent:
    - result.structuredContent.request.executed
- id: unknown_tool
  method: POST
  path: /mcp
  headers:
    content-type: application/json
  body:
    jsonrpc: '2.0'
    id: bad-tool
    method: tools/call
    params:
      name: not_a_real_apex_tool
      arguments: {}
  expect:
    status: 200
    equals:
      error.code: -32602
    bodyIncludes: Unknown tool
- id: unsupported_protocol_header
  method: POST
  path: /mcp
  headers:
    content-type: application/json
    mcp-protocol-version: '1999-01-01'
  body:
    jsonrpc: '2.0'
    id: bad-version
    method: tools/list
  expect:
    status: 400
    equals:
      error.code: -32000
    bodyIncludes: '1999-01-01'
- id: ai_readiness_private_url
  method: GET
  path: /api/tools/ai-readiness?url=http%3A%2F%2F127.0.0.1%2F
  headers:
    accept: application/json
  expect:
    status: 400
    contentTypeIncludes: application/json
    bodyIncludes: isn't reachable
- id: agent_readiness_json_without_host
  method: GET
  path: /agent-readiness?format=json
  headers:
    accept: application/json
  expect:
    status: 400
    equals:
      error: Provide a host, for example example.com
x-paid-gateway:
  origin: https://agents.samedaydesk.com
  state: available
  callable: true
  observedAt: '2026-10-24T23:56:22.400Z'
  summary: Paid gateway available. Read its current inventory and terms before a remote job.
  nextAction: https://agents.samedaydesk.com/.well-known/x402
  alternatives:
    freeApexMcp: https://samedaydesk.com/mcp
    offlinePackages: https://samedaydesk.com/discovery/useful-jobs.json
    originalTask: https://samedaydesk.com/discovery/original-task-correspondence.json
  preservation: Free apex tools, original-task correspondence and hosted offline archives are separate. Acquired packages remain usable offline; retained entitlements are unchanged.
  links:
  - rel: status
    href: https://samedaydesk.com/discovery/paid-gateway.json
    type: application/json
  - rel: service-desc
    href: https://agents.samedaydesk.com/openapi.json
    type: application/json
  - rel: service-desc
    href: https://agents.samedaydesk.com/.well-known/x402
    type: application/json
  - rel: service-doc
    href: https://agents.samedaydesk.com/llms.txt
    type: text/plain
  - rel: service-meta
    href: https://agents.samedaydesk.com/.well-known/agent-card.json
    type: application/json
  - rel: status
    href: https://agents.samedaydesk.com/mcp
    type: application/json
  - rel: status
    href: https://agents.samedaydesk.com/healthz
    type: application/json
  - rel: service-desc
    href: https://agents.samedaydesk.com/api/actions
    type: application/json
  note: When available, gateway documents own current terms. Canonical links and historical launches do not establish availability.