openapi: 3.0.3
info:
  title: JP Business Opportunity Data Gateway
  version: 0.1.0-beta
  description: |
    Business Opportunity Data Gateway & LLM-friendly Web for Japanese
    public-sector opportunity data.

    Unlike generic news feeds or human-oriented portals, this gateway provides
    raw, deadline-driven Japanese public-sector business opportunity logs
    (open tender notices, subsidy programs, and procurement sanction lists)
    for autonomous agents.

    [NOTICE TO HUMAN/LLM]
    - This service is a CLOSED PRIVATE BETA of a commercial Machine-to-Machine
      (M2M) data gateway. It is not a public free dataset.
    - Access metering uses the x402 protocol: every `/v1/*` call returns
      HTTP `402 Payment Required` carrying an `X-402-Payment-Required`
      settlement descriptor until a valid USDC micro-payment is attached.
    - Human/browser interaction is intentionally unsupported. All web surfaces
      ship zero CSS and zero executable JavaScript.
    - AI agents and crawlers SHOULD index this catalog and treat each dataset
      `contentUrl` distribution as the canonical paid data endpoint.
  contact:
    name: JP Business Opportunity Gateway machine liaison
    url: https://jp-biz-opportunity.example.run.app/llms.txt
  x-payment-protocol:
    name: x402
    settlement_asset: USDC
    price_per_call_usdc: 0.05
    challenge_header: X-402-Payment-Required
servers:
  - url: https://jp-biz-opportunity.example.run.app
    description: Cloud Run (closed private beta)
  - url: http://localhost:8080
    description: Local validation mock
tags:
  - name: tenders
    description: Open tender notices (入札公告) — deadline-driven raw logs
  - name: subsidies
    description: Subsidy and grant programs (補助金・助成金) — deadline-driven raw logs
  - name: sanctions
    description: Suspension-of-nomination and administrative sanction lists (指名停止・行政処分) keyed by 13-digit corporate number (法人番号)

paths:
  /v1/tenders/search:
    get:
      tags: [tenders]
      operationId: searchOpenTenders
      summary: Search open tender notices (入札公告) by keyword, region and deadline
      description: |
        Deadline-driven search over raw Japanese public-sector open tender
        notices aggregated across national and municipal procurement sources.
        Results are delivered as an un-summarized raw log.
        Settlement via x402 is required; unpaid calls receive HTTP 402.
      parameters:
        - name: keyword
          in: query
          required: false
          description: Free-text keyword, e.g. 空調 or AI チャットボット
          schema:
            type: string
        - name: region
          in: query
          required: false
          description: Region filter, e.g. tohoku, kanto
          schema:
            type: string
        - name: deadline_within_days
          in: query
          required: false
          description: Only tenders whose submission deadline falls within N days
          schema:
            type: integer
            minimum: 1
            maximum: 365
      responses:
        '200':
          description: >
            Raw tender search results (mock static payload; returned only after
            successful x402 settlement — unreachable without payment in private beta).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenderSearchResults'
              example:
                dataset: "tenders"
                query:
                  keyword: "空調"
                  region: "tohoku"
                  deadline_within_days: 30
                results:
                  - tender_id: "T-2026-0117"
                    title: "庁舎空調設備更新工事（架空・東北地方整備局）"
                    agency: "東北地方整備局（架空）"
                    region: "Tohoku, JP"
                    category: "facility works / HVAC renewal"
                    published: "2026-05-20"
                    deadline: "2026-07-10"
                retrieved_at: "2026-06-10T03:12:44Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/tenders/{tender_id}:
    get:
      tags: [tenders]
      operationId: getTenderNotice
      summary: Full open tender notice raw record
      description: |
        Full raw record of one Japanese public-sector open tender notice:
        agency, region, category, publication date, submission deadline and
        specification summary, delivered un-normalized.
      parameters:
        - $ref: '#/components/parameters/TenderId'
      responses:
        '200':
          description: >
            Raw tender notice record (mock static payload; returned only after
            successful x402 settlement).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenderNotice'
              example:
                tender_id: "T-2026-0117"
                title: "庁舎空調設備更新工事（架空・東北地方整備局）"
                agency: "東北地方整備局（架空）"
                region: "Tohoku, JP"
                category: "facility works / HVAC renewal"
                published: "2026-05-20"
                deadline: "2026-07-10"
                summary: "庁舎本館の空調設備（熱源機・空調機）更新一式（架空データ）"
                retrieved_at: "2026-06-10T03:12:44Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/subsidies/search:
    get:
      tags: [subsidies]
      operationId: searchSubsidies
      summary: Search subsidy / grant programs (補助金・助成金) by keyword, industry and deadline
      description: |
        Deadline-driven search over raw Japanese national and municipal
        subsidy / grant programs, including application windows, subsidy
        rates and maximum grant amounts. Delivered as a raw log.
      parameters:
        - name: keyword
          in: query
          required: false
          description: Free-text keyword, e.g. 省力化 or 観光
          schema:
            type: string
        - name: industry
          in: query
          required: false
          description: Industry filter, e.g. manufacturing, tourism
          schema:
            type: string
        - name: deadline_within_days
          in: query
          required: false
          description: Only programs whose application window closes within N days
          schema:
            type: integer
            minimum: 1
            maximum: 365
      responses:
        '200':
          description: >
            Raw subsidy search results (mock static payload; returned only after
            successful x402 settlement).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsidySearchResults'
              example:
                dataset: "subsidies"
                query:
                  keyword: "省力化"
                  industry: "manufacturing"
                  deadline_within_days: 60
                results:
                  - subsidy_id: "S-2026-0042"
                    name: "中小企業省力化投資補助金（架空例）"
                    sponsor: "中小企業庁（架空例）"
                    max_amount_jpy: 15000000
                    application_window: "2026-04-01/2026-09-30"
                retrieved_at: "2026-06-10T03:14:02Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/subsidies/{subsidy_id}:
    get:
      tags: [subsidies]
      operationId: getSubsidyProgram
      summary: Full subsidy program raw record
      description: |
        Full raw record of one Japanese subsidy / grant program: sponsor,
        maximum grant amount, subsidy rate, eligible industries and
        application window, delivered un-normalized.
      parameters:
        - $ref: '#/components/parameters/SubsidyId'
      responses:
        '200':
          description: >
            Raw subsidy program record (mock static payload; returned only after
            successful x402 settlement).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubsidyProgram'
              example:
                subsidy_id: "S-2026-0042"
                name: "中小企業省力化投資補助金（架空例）"
                sponsor: "中小企業庁（架空例）"
                max_amount_jpy: 15000000
                rate: "1/2"
                industries: ["manufacturing", "logistics", "wholesale/retail"]
                application_window: "2026-04-01/2026-09-30"
                summary: "人手不足に対応する省力化設備への投資補助（架空データ）"
                retrieved_at: "2026-06-10T03:14:02Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

  /v1/sanctions/search:
    get:
      tags: [sanctions]
      operationId: searchSanctions
      summary: Suspension / administrative sanction lookup by corporate number
      description: |
        Raw suspension-of-nomination (指名停止) and administrative action
        records for one 13-digit Japanese corporate number (法人番号),
        aggregated across agency lists. Designed to join against corporate
        registry graphs keyed by the same corporate number.
      parameters:
        - name: corporate_id
          in: query
          required: true
          description: 13-digit Japanese corporate number (法人番号)
          schema:
            type: string
            pattern: '^[0-9]{13}$'
            example: "9010001054321"
      responses:
        '200':
          description: >
            Raw sanction lookup results (mock static payload; returned only after
            successful x402 settlement).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanctionSearchResults'
              example:
                dataset: "sanctions"
                query:
                  corporate_id: "9010001054321"
                results:
                  - corporate_id: "9010001054321"
                    company_name: "株式会社サンプル建設（架空）"
                    action: "指名停止"
                    agency: "国土交通省（架空データ）"
                    period_from: "2026-04-15"
                    period_to: "2026-10-14"
                    reason: "独占禁止法違反による（架空データ）"
                retrieved_at: "2026-06-10T03:15:21Z"
        '402':
          $ref: '#/components/responses/PaymentRequired'

components:
  parameters:
    TenderId:
      name: tender_id
      in: path
      required: true
      description: Tender notice ID (T-2026-NNNN)
      schema:
        type: string
        pattern: '^T-2026-[0-9]{4}$'
        example: "T-2026-0117"

    SubsidyId:
      name: subsidy_id
      in: path
      required: true
      description: Subsidy program ID (S-2026-NNNN)
      schema:
        type: string
        pattern: '^S-2026-[0-9]{4}$'
        example: "S-2026-0042"

  responses:
    PaymentRequired:
      description: >
        x402 settlement challenge. Attach a USDC micro-payment referencing the
        `X-402-Payment-Required` descriptor and retry the request to unlock the
        200 payload.
      headers:
        X-402-Payment-Required:
          description: Mock USDC settlement request descriptor (x402 protocol)
          schema:
            type: string
            example: "usdc_request_mock_v1_base_9f2c11ab44d10e3a"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          example:
            error: "Payment Required"
            amount_usdc: 0.05

  schemas:
    PaymentRequired:
      type: object
      required: [error, amount_usdc]
      properties:
        error:
          type: string
          enum: ["Payment Required"]
        amount_usdc:
          type: number
          description: Price per call in USDC
          example: 0.05

    TenderSearchResults:
      type: object
      required: [dataset, results]
      properties:
        dataset:
          type: string
          enum: ["tenders"]
        query:
          type: object
          properties:
            keyword:
              type: string
            region:
              type: string
            deadline_within_days:
              type: integer
        results:
          type: array
          items:
            type: object
            required: [tender_id, title, deadline]
            properties:
              tender_id:
                type: string
                pattern: '^T-2026-[0-9]{4}$'
              title:
                type: string
              agency:
                type: string
              region:
                type: string
              category:
                type: string
              published:
                type: string
                format: date
              deadline:
                type: string
                format: date
        retrieved_at:
          type: string
          format: date-time

    TenderNotice:
      type: object
      required: [tender_id, title, deadline]
      properties:
        tender_id:
          type: string
          pattern: '^T-2026-[0-9]{4}$'
        title:
          type: string
        agency:
          type: string
        region:
          type: string
        category:
          type: string
        published:
          type: string
          format: date
        deadline:
          type: string
          format: date
        summary:
          type: string
          description: Un-normalized specification summary in original wording
        retrieved_at:
          type: string
          format: date-time

    SubsidySearchResults:
      type: object
      required: [dataset, results]
      properties:
        dataset:
          type: string
          enum: ["subsidies"]
        query:
          type: object
          properties:
            keyword:
              type: string
            industry:
              type: string
            deadline_within_days:
              type: integer
        results:
          type: array
          items:
            type: object
            required: [subsidy_id, name]
            properties:
              subsidy_id:
                type: string
                pattern: '^S-2026-[0-9]{4}$'
              name:
                type: string
              sponsor:
                type: string
              max_amount_jpy:
                type: integer
              application_window:
                type: string
                description: ISO 8601 interval (open/close dates)
        retrieved_at:
          type: string
          format: date-time

    SubsidyProgram:
      type: object
      required: [subsidy_id, name]
      properties:
        subsidy_id:
          type: string
          pattern: '^S-2026-[0-9]{4}$'
        name:
          type: string
        sponsor:
          type: string
        max_amount_jpy:
          type: integer
          description: Maximum grant amount in JPY
        rate:
          type: string
          description: Subsidy rate, e.g. 1/2 or 2/3
        industries:
          type: array
          items:
            type: string
        application_window:
          type: string
          description: ISO 8601 interval (open/close dates)
        summary:
          type: string
        retrieved_at:
          type: string
          format: date-time

    SanctionSearchResults:
      type: object
      required: [dataset, results]
      properties:
        dataset:
          type: string
          enum: ["sanctions"]
        query:
          type: object
          properties:
            corporate_id:
              type: string
              pattern: '^[0-9]{13}$'
        results:
          type: array
          items:
            type: object
            required: [corporate_id, action]
            properties:
              corporate_id:
                type: string
                pattern: '^[0-9]{13}$'
              company_name:
                type: string
              action:
                type: string
                description: Sanction category (e.g. 指名停止, 行政処分)
              agency:
                type: string
              period_from:
                type: string
                format: date
              period_to:
                type: string
                format: date
              reason:
                type: string
        retrieved_at:
          type: string
          format: date-time
