CodeAtlas Discovery API

openapi: 3.2.0
info:
  title: Codeatlas Com Br Discovery API
  version: 1.0.0
  contact:
    name: CodeAtlas
    email: contato@codeatlas.com.br
    url: https://codeatlas.com.br/
  description: 'Operations tagged Discovery across 2 of this provider''s published API definitions: codeatlas-com-br-openapi.json, codeatlas-com-br-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://codeatlas.com.br/api/v1
  description: Production API
- url: https://codeatlas.com.br/api/sandbox/v1
  description: 'Sandbox: fixture data, nothing is delivered or stored. Same paths and OAuth flow as production; request tokens with resource=https://codeatlas.com.br/api/sandbox/v1.'
security: []
tags:
- name: Discovery
  description: Service and API discovery endpoints.
paths:
  /services:
    get:
      operationId: listServices
      summary: List CodeAtlas services
      description: Returns the public CodeAtlas service catalog, including use cases, capabilities, and delivery timelines.
      tags:
      - Discovery
      responses:
        '200':
          description: A page of services.
          headers:
            Access-Control-Allow-Origin:
              description: Always *.
              schema:
                type: string
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceListResponse'
        '400':
          description: A query parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: The HTTP method is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Allow:
              description: Supported methods.
              schema:
                type: string
        default:
          description: Unexpected error. Same shape as every other error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size, 1 to 100.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        required: false
        description: 'Opaque cursor: the next_cursor value of the previous page.'
        schema:
          type: string
          pattern: ^[0-9]+$
      security: []
    servers:
    - url: https://codeatlas.com.br/api/v1
      description: Production API
    - url: https://codeatlas.com.br/api/sandbox/v1
      description: 'Sandbox: fixture data, nothing is delivered or stored. Same paths and OAuth flow as production; request tokens with resource=https://codeatlas.com.br/api/sandbox/v1.'
  /services/{slug}:
    get:
      operationId: getService
      summary: Get one CodeAtlas service
      description: Returns a single service by its stable URL slug.
      tags:
      - Discovery
      parameters:
      - name: slug
        in: path
        required: true
        description: Stable service identifier returned by listServices.
        schema:
          type: string
          enum:
          - produto-digital
          - zelvo-ai
          - consultoria
      responses:
        '200':
          description: The service.
          headers:
            Access-Control-Allow-Origin:
              description: Always *.
              schema:
                type: string
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: The HTTP method is not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Allow:
              description: Supported methods.
              schema:
                type: string
        default:
          description: Unexpected error. Same shape as every other error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
      security: []
    servers:
    - url: https://codeatlas.com.br/api/v1
      description: Production API
    - url: https://codeatlas.com.br/api/sandbox/v1
      description: 'Sandbox: fixture data, nothing is delivered or stored. Same paths and OAuth flow as production; request tokens with resource=https://codeatlas.com.br/api/sandbox/v1.'
  /services/batch:
    post:
      operationId: batchGetServices
      summary: Get up to 50 services in one call
      description: 'Looks up each slug and returns one result per slug, in request order. A missing or non-string slug does not fail the request: its result carries status and an error object. Public, no token.'
      tags:
      - Discovery
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            examples:
              mixed:
                summary: One valid and one unknown slug
                value:
                  slugs:
                  - zelvo-ai
                  - nope
      responses:
        '200':
          description: One result per requested slug.
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        default:
          $ref: '#/components/responses/UnexpectedError'
    servers:
    - url: https://codeatlas.com.br/api/v1
      description: Production API
    - url: https://codeatlas.com.br/api/sandbox/v1
      description: 'Sandbox: fixture data, nothing is delivered or stored. Same paths and OAuth flow as production; request tokens with resource=https://codeatlas.com.br/api/sandbox/v1.'
components:
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    XRateLimitReset:
      description: Legacy. Seconds until the window resets.
      schema:
        type: integer
    RateLimit:
      description: IETF draft-ietf-httpapi-ratelimit-headers. Remaining quota r and seconds until reset t for the named policy.
      schema:
        type: string
      example: '"read";r=119;t=45'
    XRateLimitLimit:
      description: Legacy. Requests allowed per window.
      schema:
        type: integer
    XRateLimitRemaining:
      description: Legacy. Requests left in the window.
      schema:
        type: integer
    RateLimitPolicy:
      description: Quota q and window w in seconds of the policy that applies.
      schema:
        type: string
      example: '"read";q=120;w=60'
  schemas:
    BatchRequest:
      type: object
      required:
      - slugs
      properties:
        slugs:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
          description: Service slugs, 1 to 50.
      additionalProperties: false
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - hint
          properties:
            code:
              type: string
              enum:
              - bad_request
              - conflict
              - forbidden
              - invalid_token
              - method_not_allowed
              - not_found
              - payload_too_large
              - rate_limited
              - unauthorized
              - unprocessable
              - unsupported_media_type
              description: Stable machine-readable code.
            message:
              type: string
              description: Human-readable description.
            hint:
              type: string
              description: How to fix the request.
          additionalProperties: false
      additionalProperties: false
      examples:
      - error:
          code: unauthorized
          message: This endpoint requires a Bearer access token.
          hint: 'Register a client at POST /oauth2/register, request a token at POST /oauth2/token and send it as Authorization: Bearer <token>.'
    ServiceListResponse:
      type: object
      required:
      - data
      - count
      - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Service'
        count:
          type: integer
          minimum: 0
          description: Total number of services, not the page size.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as cursor to get the next page. null on the last page.
      additionalProperties: false
    Service:
      type: object
      required:
      - slug
      - name
      - description
      - serviceType
      - url
      - capabilities
      - deliveryTimeline
      properties:
        slug:
          type: string
          description: Stable service identifier.
        name:
          type: string
          description: Human-readable service name.
        description:
          type: string
          description: Plain-language service description.
        serviceType:
          type: string
          description: Structured service category.
        url:
          type: string
          format: uri
          description: Canonical service page.
        capabilities:
          type: array
          items:
            type: string
          description: Capabilities included in the service.
        deliveryTimeline:
          type: string
          description: Typical initial delivery timeline. An estimate, not a commitment.
      additionalProperties: false
      examples:
      - slug: zelvo-ai
        name: Atendimento Inteligente com Zelvo.AI
        description: Agentes de atendimento com IA para escalar o relacionamento com clientes sem perder contexto e qualidade.
        serviceType: Automação com Inteligência Artificial
        url: https://codeatlas.com.br/solucoes#zelvo-ai
        capabilities:
        - customer support
        - lead qualification
        - WhatsApp
        - CRM
        - knowledge bases
        deliveryTimeline: 3 a 8 semanas para um fluxo inicial
    ServiceResponse:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/Service'
      additionalProperties: false
    BatchResult:
      type: object
      required:
      - slug
      - status
      properties:
        slug:
          type:
          - string
          - 'null'
        status:
          type: integer
          description: 'HTTP-style status of this item: 200, 404 or 400.'
        data:
          $ref: '#/components/schemas/Service'
        error:
          type: object
          required:
          - code
          - message
          - hint
          properties:
            code:
              type: string
            message:
              type: string
            hint:
              type: string
          additionalProperties: false
      additionalProperties: false
    BatchResponse:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/BatchResult'
      additionalProperties: false
  responses:
    BadRequest:
      description: 'The request is malformed: invalid query parameter, invalid JSON or invalid Idempotency-Key.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnexpectedError:
      description: Unexpected error. Same shape as every other error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayloadTooLarge:
      description: The body is larger than 16384 bytes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unprocessable:
      description: A field failed validation, or the Idempotency-Key was reused with a different body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: The body must be application/json.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MethodNotAllowed:
      description: The HTTP method is not supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Allow:
          description: Supported methods.
          schema:
            type: string
    RateLimited:
      description: Rate limit exceeded. Wait Retry-After seconds.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client_credentials. Register a client at POST /oauth2/register, then POST /oauth2/token. Tokens are JWTs valid for 3600 seconds. For the sandbox request a token with resource=https://codeatlas.com.br/api/sandbox/v1.
      flows:
        clientCredentials:
          tokenUrl: https://codeatlas.com.br/oauth2/token
          scopes:
            api:write: Create contact requests and exports.
externalDocs:
  description: Developer documentation
  url: https://codeatlas.com.br/docs
x-refined-from:
- codeatlas-com-br-openapi.json
- codeatlas-com-br-openapi.yml
x-sandbox:
  url: https://codeatlas.com.br/api/sandbox/v1
  description: Test mode for the whole API. Read endpoints return fixture services (sandbox-one, sandbox-two). POST /contact-requests is accepted and answers delivery=sandbox but is never emailed or stored. Exports and batch work on the fixtures. Sandbox and production tokens are not interchangeable.
  auth: Same OAuth client_credentials flow. Request tokens with resource=https://codeatlas.com.br/api/sandbox/v1.
  health: https://codeatlas.com.br/api/sandbox/v1/health
  documentation: https://codeatlas.com.br/auth.md