openapi: 3.1.0
info:
  title: DGTL Connector docs discovery
  description: >-
    Public docs-discovery surface for DGTL Connector by DGTL Sunrise. Agents use these routes to
    find install docs, capabilities, OpenAPI, and the docs MCP. This is not a public Ads account
    API.


    Versioning policy: URL path versioning under /v1/docs-discovery/* (major version in the path).
    Breaking changes publish a new /vN path. Deprecated routes send Deprecation and Sunset headers
    and remain available until the Sunset date. See /api/versioning-policy.
  version: 1.0.0
  contact:
    name: DGTL Sunrise
    email: support@dgtlsunrise.com
    url: https://www.dgtlsunrise.com/developers
  license:
    name: Apache-2.0
servers:
  - url: https://www.dgtlsunrise.com
    description: Production docs site
paths:
  /v1/docs-discovery/health:
    get:
      operationId: getDocsDiscoveryHealth
      summary: Docs discovery health
      description: Lightweight JSON health check for the public docs-discovery surface.
      responses:
        '200':
          description: Health payload
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /openapi.json:
    get:
      operationId: getOpenApi
      summary: OpenAPI document
      description: Machine-readable OpenAPI description of the public docs-discovery routes.
      responses:
        '200':
          description: OpenAPI document
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenApiDocument'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/openapi.yaml:
    get:
      operationId: getOpenApiYaml
      summary: OpenAPI YAML
      description: YAML twin of /openapi.json.
      responses:
        '200':
          description: OpenAPI YAML
          headers:
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
            API-Version:
              schema:
                type: string
          content:
            application/yaml:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
  /agent.json:
    get:
      operationId: getAgentJson
      summary: Structured agent capabilities
      description: Product capabilities, install facts, and agent discovery links for DGTL Connector.
      responses:
        '200':
          description: Agent document
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDocument'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /:
    get:
      operationId: getHomepageAgentMode
      summary: Homepage agent mode
      description: When mode=agent, returns the same document as /agent.json.
      responses:
        '200':
          description: Agent document when mode=agent
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDocument'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      parameters:
        - name: mode
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: Set to agent for the JSON agent document.
  /llms.txt:
    get:
      operationId: getLlmsTxt
      summary: llms.txt navigation index
      description: Short markdown index of public docs for agents.
      responses:
        '200':
          description: Markdown index
          headers:
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
            API-Version:
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
  /developers:
    get:
      operationId: getDevelopers
      summary: Developer resources
      description: JSON discovery stub when Accept prefers JSON; HTML/markdown otherwise.
      responses:
        '200':
          description: Discovery stub for JSON clients
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryStub'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /server.json:
    get:
      operationId: getMcpServerJson
      summary: Local MCP server.json
      description: MCP Registry-shaped manifest for the local stdio DGTL Connector plugin.
      responses:
        '200':
          description: MCP server manifest
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerJson'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /.well-known/mcp/server-card.json:
    get:
      operationId: getMcpServerCard
      summary: MCP server card
      description: Well-known MCP server card including the remote docs MCP endpoint.
      responses:
        '200':
          description: MCP server card
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerCard'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /.well-known/mcp.json:
    get:
      operationId: getWellKnownMcpJson
      summary: Well-known MCP alias
      description: Alias of the MCP server card at /.well-known/mcp.json.
      responses:
        '200':
          description: MCP server card
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerCard'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /mcp:
    post:
      operationId: postMcp
      summary: Docs MCP Streamable HTTP
      description: JSON-RPC Streamable HTTP MCP endpoint for docs discovery tools.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - method
              properties:
                jsonrpc:
                  type: string
                  enum:
                    - '2.0'
                id: {}
                method:
                  type: string
                params:
                  type: object
      responses:
        '200':
          description: JSON-RPC response
          headers:
            RateLimit:
              schema:
                type: string
            RateLimit-Policy:
              schema:
                type: string
            API-Version:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                properties:
                  jsonrpc:
                    type: string
                  id: {}
                  result:
                    type: object
                  error:
                    type: object
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
            RateLimit:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    get:
      operationId: getMcp
      summary: Docs MCP endpoint info
      description: Returns how to connect to the docs MCP over Streamable HTTP.
      responses:
        '200':
          description: MCP endpoint info
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - transport
                  - url
                properties:
                  ok:
                    type: boolean
                  transport:
                    type: string
                  url:
                    type: string
                    format: uri
                  protocolVersions:
                    type: array
                    items:
                      type: string
        '404':
          $ref: '#/components/responses/NotFound'
  /api/versioning-policy:
    get:
      operationId: getVersioningPolicy
      summary: API versioning and deprecation policy
      description: Machine-readable versioning and deprecation policy for docs-discovery routes.
      responses:
        '200':
          description: Versioning policy
          headers:
            RateLimit:
              description: IETF RateLimit structured field
              schema:
                type: string
            RateLimit-Policy:
              description: IETF RateLimit-Policy structured field
              schema:
                type: string
            API-Version:
              description: Docs-discovery API major version
              schema:
                type: string
                example: '1'
          content:
            application/json:
              schema:
                type: object
                required:
                  - api_version
                  - strategy
                  - deprecation
                properties:
                  api_version:
                    type: string
                  strategy:
                    type: string
                  deprecation:
                    type: object
                    required:
                      - headers
                      - policy_url
                    properties:
                      headers:
                        type: array
                        items:
                          type: string
                      policy_url:
                        type: string
                        format: uri
                      summary:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: Sitemap
      responses:
        '200':
          description: XML sitemap
          headers:
            RateLimit:
              schema:
                type: string
            API-Version:
              schema:
                type: string
          content:
            application/xml:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - detail
        - code
        - message
        - resolution
      additionalProperties: false
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        code:
          type: string
        message:
          type: string
        resolution:
          type: string
    Health:
      type: object
      required:
        - ok
        - service
        - openapi
      additionalProperties: false
      properties:
        ok:
          type: boolean
        service:
          type: string
        openapi:
          type: string
    DiscoveryStub:
      type: object
      required:
        - ok
        - path
        - message
        - links
      additionalProperties: false
      properties:
        ok:
          type: boolean
        path:
          type: string
        message:
          type: string
        links:
          type: object
          additionalProperties:
            type: string
    AgentDocument:
      type: object
      required:
        - name
        - product
        - url
        - description
      properties:
        name:
          type: string
        product:
          type: string
        url:
          type: string
          format: uri
        mode:
          type: string
        description:
          type: string
        install:
          type: object
        authentication:
          type: object
        apis:
          type: object
        capabilities:
          type: array
        agent_discovery:
          type: object
        contact:
          type: object
    McpServerJson:
      type: object
      required:
        - name
        - description
        - version
      properties:
        name:
          type: string
        title:
          type: string
        description:
          type: string
        version:
          type: string
        websiteUrl:
          type: string
          format: uri
        repository:
          type: object
    McpServerCard:
      type: object
      required:
        - name
        - title
        - description
        - version
      properties:
        name:
          type: string
        title:
          type: string
        description:
          type: string
        version:
          type: string
        websiteUrl:
          type: string
          format: uri
        repository:
          type: object
        remotes:
          type: array
          items:
            type: object
    OpenApiDocument:
      type: object
      description: OpenAPI 3.1 document
  responses:
    NotFound:
      description: Not found
      headers:
        RateLimit:
          schema:
            type: string
        RateLimit-Policy:
          schema:
            type: string
        API-Version:
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
        application/json:
          schema:
            $ref: '#/components/schemas/Problem'