Eurobase Account API

openapi: 3.2.0
info:
  title: Eurobase Account API
  version: 0.2.0
  description: Eurobase deployment control-plane API.
servers:
- url: https://api.eurobase.dev
tags:
- name: Account
paths:
  /account/usage:
    get:
      summary: Read account usage and plan screen model
      description: Returns one coherent monthly snapshot containing account meters, resource contributors, projection freshness, and a separate UTC-day action-quota projection. When organizationId is supplied, plan resolution is organization-exclusive and never falls back to the requesting user subscription.
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: organizationId
        required: false
        schema:
          type: string
        description: Reads the usage and plan screen for an organization the user belongs to.
      - in: query
        name: billingMonth
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}(-\d{2})?$
        description: Reads a closed billing month when supplied; omitted reads the current month.
      responses:
        '200':
          description: Account usage summary with recorded values and projection status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
      tags:
      - Account
      operationId: getAccountUsage
      x-operation-id-source: derived
  /account/usage/resource-contributors:
    get:
      summary: Read account usage top resource contributors
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: organizationId
        required: false
        schema:
          type: string
        description: Reads visible resource contributors for an organization the user belongs to.
      - in: query
        name: billingMonth
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}(-\d{2})?$
        description: Reads a closed billing month when supplied; omitted reads the current month.
      responses:
        '200':
          description: Account usage top resource contributors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageResourceContributorsResponse'
      tags:
      - Account
      operationId: getAccountUsageResourceContributors
      x-operation-id-source: derived
  /account/billing:
    get:
      summary: Read account billing screen model
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: organizationId
        required: false
        schema:
          type: string
        description: Reads the billing state for an organization the user belongs to. When omitted, the only organization of the user is read; a user without any project reads their Free plan with a null scope.
      responses:
        '200':
          description: Account billing summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBillingResponse'
        '400':
          description: Organization is required
        '404':
          description: Organization not found
      tags:
      - Account
      operationId: getAccountBilling
      x-operation-id-source: derived
  /account/usage/timeseries:
    get:
      summary: Read account usage time-series buckets for visible meters
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: organizationId
        required: false
        schema:
          type: string
        description: Reads visible project usage buckets for an organization the user belongs to.
      - in: query
        name: metricCodes
        required: true
        schema:
          type: string
        description: Comma-separated, distinct usage metric codes to aggregate from usage_counters in one read; series are returned in this order. runtime_average_latency_ms is API-derived from runtime_latency_ms_sum divided by runtime_requests.
      - in: query
        name: range
        required: false
        schema:
          type: string
          enum:
          - 24h
          - 7d
          - 30d
          - 90d
          default: 30d
      - in: query
        name: bucket
        required: false
        schema:
          type: string
          enum:
          - 1h
          - 1d
          default: 1d
      responses:
        '200':
          description: Account usage time-series buckets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageTimeSeriesResponse'
        '400':
          description: Invalid or duplicate metric, range, or bucket
        '404':
          description: Organization not found
      tags:
      - Account
      operationId: getAccountUsageTimeseries
      x-operation-id-source: derived
  /account/domains:
    get:
      summary: List the custom domains of a workspace
      description: The workspace owner sees every domain of the workspace; a project member sees the domains linked to their projects. Each domain names the project it serves, if any, lists the two DNS records to add where the domain DNS lives, and shows what public DNS reports.
      parameters:
      - in: query
        name: organizationId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Workspace domains
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceDomainsResponse'
        '400':
          description: organizationId missing (organization-id-required)
        '404':
          description: Not a member of this workspace (workspace-not-found)
      tags:
      - Account
      operationId: getAccountDomains
      x-operation-id-source: derived
    post:
      summary: Connect a custom domain to a workspace
      description: Workspace owner only, within the workspace plan limit. With projectId the domain serves that project once its _acme-challenge CNAME is verified and its certificate is issued; without it the domain waits in the workspace and serves nothing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceDomainRequest'
      responses:
        '201':
          description: Domain connected, waiting for its DNS records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDomainResponse'
        '400':
          description: organizationId missing (organization-id-required), not a public domain name (project-domain-invalid), a Eurobase address (project-domain-platform-zone) or an invalid projectId (project-domain-target-invalid)
        '403':
          description: Only the workspace owner can manage its domains (workspace-domain-owner-required)
        '409':
          description: Already in the workspace (project-domain-exists), domain limit reached (project-domain-limit-reached) or a project outside the workspace (project-domain-workspace-mismatch)
        '429':
          description: Too many domains connected by this user today
        '503':
          description: Custom domains are not available (project-domains-not-configured)
      tags:
      - Account
      operationId: postAccountDomains
      x-operation-id-source: derived
  /account/domains/{domainId}:
    patch:
      summary: Link a custom domain to a project, move it, or unlink it
      description: Workspace owner only. projectId names a project of the workspace, or null to unlink. DNS records and the certificate stay valid; an active domain serves the linked project production deployment at once, and serves nothing while unlinked.
      parameters:
      - in: path
        name: domainId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - projectId
              properties:
                projectId:
                  type:
                  - string
                  - 'null'
      responses:
        '200':
          description: Domain linked, moved or unlinked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDomainResponse'
        '400':
          description: projectId missing (project-domain-target-required) or invalid (project-domain-target-invalid)
        '403':
          description: Only the workspace owner can manage its domains (workspace-domain-owner-required)
        '404':
          description: Domain not found (project-domain-not-found)
        '409':
          description: A project outside the workspace (project-domain-workspace-mismatch)
        '429':
          description: Too many changes by this user this hour
      tags:
      - Account
      operationId: patchAccountDomainsByDomainId
      x-operation-id-source: derived
    delete:
      summary: Remove a custom domain from the workspace
      parameters:
      - in: path
        name: domainId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Domain removed; it stops serving immediately
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                properties:
                  ok:
                    type: boolean
        '403':
          description: Only the workspace owner can manage its domains (workspace-domain-owner-required)
        '404':
          description: Domain not found (project-domain-not-found)
      tags:
      - Account
      operationId: deleteAccountDomainsByDomainId
      x-operation-id-source: derived
components:
  schemas:
    UsageMeterRow:
      type: object
      description: Usage meter value returned by the API. Derived account meters such as runtime_average_latency_ms are computed by the API from DB-owned counters and are not accepted as persisted usage metrics.
      required:
      - code
      - label
      - unit
      - value
      properties:
        code:
          type: string
        label:
          type: string
        unit:
          type: string
        value:
          type: string
          pattern: ^[0-9]+(?:\.[0-9]+)?$
    AccountUsageTimeSeries:
      type: object
      required:
      - metricCode
      - unit
      - status
      - points
      properties:
        metricCode:
          type: string
        unit:
          type: string
        status:
          type: string
          enum:
          - available
          - empty
          - unavailable
          - unsupported
        points:
          type: array
          maxItems: 168
          items:
            $ref: '#/components/schemas/AccountUsageTimeSeriesPoint'
    AccountUsageTimeSeriesResponse:
      type: object
      required:
      - range
      - bucket
      - window
      - series
      - generatedAt
      properties:
        range:
          type: string
          enum:
          - 24h
          - 7d
          - 30d
          - 90d
        bucket:
          type: string
          enum:
          - 1h
          - 1d
        window:
          type: object
          required:
          - start
          - end
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        series:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AccountUsageTimeSeries'
        generatedAt:
          type: string
          format: date-time
    ProjectDomainResponse:
      type: object
      required:
      - domain
      properties:
        domain:
          $ref: '#/components/schemas/ProjectDomain'
    BillingSubscriptionState:
      type: object
      required:
      - state
      - label
      - planCode
      - currentPeriodEnd
      - cancelAtPeriodEnd
      - manageBillingAvailable
      properties:
        state:
          type: string
          enum:
          - free
          - granted
          - processing
          - active
          - canceling
          - past_due
          - unpaid
          - canceled
        label:
          type: string
        planCode:
          type:
          - string
          - 'null'
          enum:
          - free
          - starter
          - pro
          - null
        currentPeriodEnd:
          type:
          - string
          - 'null'
          format: date-time
        cancelAtPeriodEnd:
          type: boolean
        manageBillingAvailable:
          type: boolean
    AccountUsageResourceContributorsResponse:
      type: object
      required:
      - resourceContributors
      properties:
        resourceContributors:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/AccountUsageResourceContributor'
    AccountUsageTimeSeriesPoint:
      type: object
      required:
      - start
      - end
      - value
      - state
      - final
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        value:
          anyOf:
          - type: string
            pattern: ^[0-9]+(?:\.[0-9]+)?$
          - type: 'null'
        state:
          type: string
          enum:
          - available
          - empty
          - unavailable
        final:
          type: boolean
    AccountActionQuota:
      type: object
      description: Current API-owned abuse/action allowance. This is separate from monthly usage meters.
      additionalProperties: false
      required:
      - actionCode
      - metricCode
      - label
      - used
      - limit
      - resetAt
      - state
      - plan
      - recoveryActions
      properties:
        actionCode:
          type: string
          enum:
          - deploy
        metricCode:
          type: string
          enum:
          - deployments
        label:
          type: string
        used:
          type: string
          pattern: ^[0-9]+(?:\.[0-9]+)?$
        limit:
          type: string
          pattern: ^[0-9]+(?:\.[0-9]+)?$
        resetAt:
          type: string
          format: date-time
        state:
          type: string
          enum:
          - available
          - blocked
        plan:
          type: object
          additionalProperties: false
          required:
          - code
          - name
          - pricingVersion
          properties:
            code:
              type: string
            name:
              type: string
            pricingVersion:
              type:
              - string
              - 'null'
        recoveryActions:
          type: array
          uniqueItems: true
          items:
            type: string
            enum:
            - open_usage
            - wait_until_reset
            - request_plan_change
    UsageWindow:
      type: object
      required:
      - code
      - start
      - end
      properties:
        code:
          type: string
          enum:
          - current_month
          - billing_month
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    AccountUsageResponse:
      type: object
      required:
      - plan
      - scope
      - period
      - lastUpdatedAt
      - status
      - meters
      - runtimeUsage
      - estimatedCost
      - billingState
      - billingSubscription
      - actionQuotas
      - resourceContributors
      - projection
      properties:
        plan:
          type: object
          required:
          - code
          - name
          - pricingVersion
          properties:
            code:
              type: string
            name:
              type: string
            pricingVersion:
              type:
              - string
              - 'null'
        scope:
          type: object
          required:
          - kind
          - organizationId
          - userId
          properties:
            kind:
              type: string
              enum:
              - user
              - organization
            organizationId:
              type:
              - string
              - 'null'
            userId:
              type:
              - string
              - 'null'
        period:
          $ref: '#/components/schemas/UsageWindow'
        lastUpdatedAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - available
          - empty
          - unavailable
        meters:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/UsageMeterRow'
            - type: object
              required:
              - used
              - limit
              - resetAt
              - state
              - recoveryActions
              properties:
                used:
                  type: string
                  pattern: ^[0-9]+(?:\.[0-9]+)?$
                reserved:
                  type: string
                  description: Build seconds held for builds in progress, separate from consumed usage.
                limit:
                  type:
                  - string
                  - 'null'
                resetAt:
                  type:
                  - string
                  - 'null'
                  format: date-time
                state:
                  type: string
                  enum:
                  - ok
                  - blocked
                  - unavailable
                recoveryActions:
                  type: array
                  items:
                    type: string
        runtimeUsage:
          oneOf:
          - type: object
            required:
            - label
            - usedSmallEquivalentHours
            - includedSmallEquivalentHours
            - remainingSmallEquivalentHours
            - state
            - sourceMeters
            - resetStrategy
            properties:
              label:
                type: string
              usedSmallEquivalentHours:
                type: string
              includedSmallEquivalentHours:
                type: string
              remainingSmallEquivalentHours:
                type: string
              state:
                type: string
                enum:
                - ok
                - blocked
              sourceMeters:
                type: array
                items:
                  type: string
              resetStrategy:
                type: string
          - type: 'null'
        estimatedCost:
          anyOf:
          - $ref: '#/components/schemas/EstimatedCost'
          - type: 'null'
        billingState:
          $ref: '#/components/schemas/BillingUsageState'
        billingSubscription:
          $ref: '#/components/schemas/BillingSubscriptionState'
        actionQuotas:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AccountActionQuota'
        resourceContributors:
          type: array
          items:
            $ref: '#/components/schemas/AccountUsageResourceContributor'
        projection:
          type: object
          required:
          - status
          - asOf
          - pendingCount
          - pendingCountIsLowerBound
          - quarantinedCount
          - quarantinedCountIsLowerBound
          - oldestPendingAt
          - lagMs
          properties:
            status:
              type: string
              enum:
              - ready
              - applying
              - delayed
              - rebuilding
              - blocked
              - unavailable
            asOf:
              type: string
              format: date-time
            pendingCount:
              type: integer
              minimum: 0
            pendingCountIsLowerBound:
              type: boolean
            quarantinedCountIsLowerBound:
              type: boolean
            quarantinedCount:
              type: integer
              minimum: 0
            oldestPendingAt:
              type:
              - string
              - 'null'
              format: date-time
            lagMs:
              type: integer
              minimum: 0
    EstimatedCost:
      type: object
      required:
      - currency
      - amount
      - label
      - pricingVersion
      properties:
        currency:
          type: string
          enum:
          - EUR
        amount:
          type: string
          pattern: ^[0-9]+\.[0-9]{2}$
        label:
          type: string
        pricingVersion:
          type: string
    ProjectDomain:
      type: object
      required:
      - id
      - hostname
      - status
      - statusReason
      - zone
      - records
      - dnsTargetState
      - certificateState
      - www
      - converging
      - checkedAt
      - activeAt
      - createdAt
      properties:
        id:
          type: string
        hostname:
          type: string
        status:
          type: string
          enum:
          - pending
          - issuing
          - active
          - failed
        statusReason:
          type:
          - string
          - 'null'
          enum:
          - verification_timeout
          - certificate_failed
          - challenge_record_missing
          - challenge_record_removed
          - null
        records:
          type: array
          description: The records to add, each with what public DNS shows. A zone apex also lists its www companion (_acme-challenge.www and www), which redirects to the apex.
          items:
            type: object
            required:
            - type
            - name
            - host
            - value
            - purpose
            - state
            properties:
              type:
                type: string
                enum:
                - CNAME
                - A
              name:
                type: string
                description: Fully qualified record name
              host:
                type:
                - string
                - 'null'
                description: Record name relative to the domain DNS zone (@ for the zone itself); null until the zone is known
              value:
                type:
                - string
                - 'null'
                description: Null only while custom domains are unavailable
              purpose:
                type: string
                enum:
                - verification
                - traffic
              state:
                type: string
                enum:
                - ok
                - waiting
                - elsewhere
                description: 'elsewhere: a traffic record that resolves to an address other than the edge'
              observed:
                type: array
                items:
                  type: string
              aliasValue:
                type: string
                description: 'For an A record: the hostname an ALIAS, ANAME or flattened CNAME may point to instead'
              acceptedValue:
                type: string
                description: 'For the www record of a zone apex: the apex, which the CNAME may point to instead'
        zone:
          type:
          - string
          - 'null'
          description: The DNS zone the domain lives in, once public DNS shows it
        dnsTargetState:
          type: string
          enum:
          - unknown
          - ok
          - elsewhere
          - missing
        certificateState:
          type: string
          enum:
          - waiting
          - issuing
          - issued
        www:
          type:
          - object
          - 'null'
          description: 'A zone apex only: its www companion, which redirects to the apex while the apex certificate covers it. requested: being added to the certificate; issued: covered; failing: covered but not renewing; failed: not covered within 24 hours, so it was removed and the apex renews alone.'
          required:
          - name
          - certificateState
          properties:
            name:
              type: string
            certificateState:
              type: string
              enum:
              - none
              - requested
              - issued
              - failing
              - failed
        converging:
          type: boolean
          description: The domain will change state without anyone acting (pending or issuing)
        checkedAt:
          type:
          - string
          - 'null'
          format: date-time
        activeAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    BillingUsageState:
      type: object
      required:
      - state
      - label
      - meterAvailability
      - billingMonth
      properties:
        state:
          type: string
          enum:
          - Estimated
          - Finalizing
          - Final
        label:
          type: string
        meterAvailability:
          type: string
          enum:
          - available
          - unavailable
        billingMonth:
          type:
          - string
          - 'null'
    AccountUsageResourceContributor:
      type: object
      required:
      - projectId
      - projectName
      - resourceType
      - resourceLabel
      - meter
      - estimatedCost
      - share
      - updatedAt
      properties:
        projectId:
          type: string
        projectName:
          type: string
        resourceType:
          type: string
        resourceLabel:
          type: string
        meter:
          anyOf:
          - $ref: '#/components/schemas/UsageMeterRow'
          - type: 'null'
        estimatedCost:
          anyOf:
          - $ref: '#/components/schemas/EstimatedCost'
          - type: 'null'
        share:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    AccountBillingResponse:
      type: object
      required:
      - plan
      - scope
      - billingSubscription
      - canManageBilling
      - lastUpdatedAt
      properties:
        plan:
          type: object
          required:
          - code
          - name
          - pricingVersion
          properties:
            code:
              type: string
            name:
              type: string
            pricingVersion:
              type:
              - string
              - 'null'
        scope:
          type: object
          required:
          - kind
          - organizationId
          - userId
          properties:
            kind:
              type: string
              enum:
              - organization
            organizationId:
              type:
              - string
              - 'null'
            userId:
              type: 'null'
        billingSubscription:
          $ref: '#/components/schemas/BillingSubscriptionState'
        canManageBilling:
          type: boolean
        lastUpdatedAt:
          type: string
          format: date-time
    WorkspaceDomainsResponse:
      type: object
      required:
      - domains
      - canManage
      - linkableProjects
      - availability
      - used
      - limit
      properties:
        canManage:
          type: boolean
          description: Whether the caller owns the workspace and so adds, links, unlinks and removes its domains
        linkableProjects:
          type: array
          description: Workspace projects a domain can be linked to; empty unless the caller owns the workspace
          items:
            type: object
            required:
            - id
            - name
            - hostname
            - repoFullName
            - branch
            properties:
              id:
                type: string
              name:
                type: string
              hostname:
                type:
                - string
                - 'null'
              repoFullName:
                type:
                - string
                - 'null'
              branch:
                type:
                - string
                - 'null'
        used:
          type: integer
          description: Domains the workspace has, linked or not; the limit applies to this count
        domains:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/ProjectDomain'
            - type: object
              required:
              - project
              properties:
                project:
                  type:
                  - object
                  - 'null'
                  description: The project the domain serves; null while it is not linked
                  required:
                  - id
                  - name
                  - hostname
                  - repoFullName
                  - branch
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    hostname:
                      type:
                      - string
                      - 'null'
                      description: The project production hostname the domain serves
                    repoFullName:
                      type:
                      - string
                      - 'null'
                    branch:
                      type:
                      - string
                      - 'null'
        availability:
          type: string
          enum:
          - available
          - unavailable
        limit:
          type: integer
          description: 'Domains this workspace may have: 1 on Free, 10 on paid plans'
    WorkspaceDomainRequest:
      type: object
      required:
      - organizationId
      - hostname
      properties:
        organizationId:
          type: string
        hostname:
          type: string
          example: example.com
        projectId:
          type:
          - string
          - 'null'
          description: The project the domain serves; omitted or null to add it unlinked
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Host-eurobase_session
    csrfHeader:
      type: apiKey
      in: header
      name: X-Eurobase-CSRF