Eurobase Storage Objects API

openapi: 3.2.0
info:
  title: Eurobase Storage Objects API
  version: 0.2.0
  description: Eurobase deployment control-plane API.
servers:
- url: https://api.eurobase.dev
tags:
- name: Storage Objects
paths:
  /storage-objects/{id}:
    get:
      summary: Get one storage object
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Storage object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectResponse'
      tags:
      - Storage Objects
      operationId: getStorageObjectsById
      x-operation-id-source: derived
    delete:
      summary: Delete one storage object
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted storage object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectResponse'
      tags:
      - Storage Objects
      operationId: deleteStorageObjectsById
      x-operation-id-source: derived
  /storage-objects/{id}/read-url:
    post:
      summary: Create a signed storage object read URL
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Signed storage object read URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateStorageObjectReadUrlResponse'
        '403':
          description: Project public serving is suspended (reason project_suspended, ADR 0080)
      tags:
      - Storage Objects
      operationId: postStorageObjectsByIdReadUrl
      x-operation-id-source: derived
  /storage-objects/{id}/preview:
    get:
      summary: Read the current authenticated storage preview derivative
      description: Rechecks project membership and current preview generation, then returns at most 256 KiB of verified WebP bytes with private no-store caching. It never returns original object bytes or a provider URL.
      security:
      - bearerAuth: []
      - sessionCookie: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Verified storage preview derivative
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - private, no-store, max-age=0
          content:
            image/webp:
              schema:
                type: string
                format: binary
                maxLength: 262144
        '401':
          description: Authentication required
        '404':
          description: Storage object not found or inaccessible
        '409':
          description: Current preview generation is not ready
        '503':
          description: Stored derivative is unavailable or fails verification
      tags:
      - Storage Objects
      operationId: getStorageObjectsByIdPreview
      x-operation-id-source: derived
  /storage-objects/{id}/preview-retry:
    post:
      summary: Retry one failed or missing storage preview
      description: Owner/admin-only retry. Direct uploads requeue the DB-owned preview job; legacy uploads use the bounded private transformer.
      security:
      - bearerAuth: []
      - sessionCookie: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Storage preview retry result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectResponse'
        '401':
          description: Authentication required
        '403':
          description: Owner/admin access required
        '404':
          description: Storage object not found
        '409':
          description: Preview is in progress, deleting, or not eligible
        '502':
          description: Original source read failed
      tags:
      - Storage Objects
      operationId: postStorageObjectsByIdPreviewRetry
      x-operation-id-source: derived
  /storage-objects/{id}/content:
    get:
      summary: Redirect a public object to its canonical filename URL or read a private signed…
      description: Anonymous ready public reads permanently redirect to the canonical filename-bearing URL without bandwidth accounting. A valid signed token returns a private attachment directly.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: query
        name: token
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Private signed storage object bytes
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Attachment disposition carrying the API-owned object-key basename
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '308':
          description: Ready public object canonical filename redirect; no object bytes are read or accounted
          headers:
            Location:
              schema:
                type: string
                format: uri
            Cache-Control:
              schema:
                type: string
                enum:
                - public, max-age=300
        '401':
          description: Private object read token required (storage-read-token-required), invalid (storage-read-token-invalid), or expired (storage-read-token-expired)
        '403':
          description: Signed read token rejected, or project public serving is suspended (reason project_suspended, ADR 0080)
        '404':
          description: Storage object not found
        '409':
          description: Read bandwidth quota blocks the content fetch before provider bytes are requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaBlockResponse'
        '500':
          description: Ready object metadata cannot produce a valid canonical filename
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectMetadataInvalidResponse'
        '503':
          description: Quota or storage accounting evidence is temporarily unavailable; no response body bytes are returned
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
            Retry-After:
              schema:
                type: string
                enum:
                - '2'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetryableStorageBlockerResponse'
      tags:
      - Storage Objects
      operationId: getStorageObjectsByIdContent
      x-operation-id-source: derived
  /storage-objects/{id}/content/{filename}:
    get:
      summary: Read public storage object content from its canonical filename URL
      description: Returns ready public raster images and PDFs inline and other public types as attachments. The encoded filename must exactly match the API-owned object-key basename; aliases and tokenized requests are rejected before accounting or provider access.
      security: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: filename
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
      responses:
        '200':
          description: Public storage object bytes
          headers:
            Content-Disposition:
              schema:
                type: string
              description: Inline or attachment disposition carrying the API-owned object-key basename
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Object, canonical filename, or anonymous public route not found
        '409':
          description: Read bandwidth quota blocks the content fetch before provider bytes are requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaBlockResponse'
        '500':
          description: Ready object metadata cannot produce a valid canonical filename
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageObjectMetadataInvalidResponse'
        '503':
          description: Quota or storage accounting evidence is temporarily unavailable; no response body bytes are returned
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
            Retry-After:
              schema:
                type: string
                enum:
                - '2'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetryableStorageBlockerResponse'
      tags:
      - Storage Objects
      operationId: getStorageObjectsByIdContentByFilename
      x-operation-id-source: derived
components:
  schemas:
    ProjectStorageBucketSummary:
      type: object
      required:
      - id
      - name
      - pathPrefix
      - accessMode
      - status
      - objectCount
      - readyCount
      - totalBytes
      - createdAt
      - visibilitySummary
      - mimeSummary
      properties:
        id:
          type: string
        name:
          type: string
        pathPrefix:
          type: string
        accessMode:
          type: string
          enum:
          - private
          - public
        status:
          type: string
          enum:
          - provisioning
          - ready
          - failed
          - pending_delete
          - delete_failed
          - deleted
        objectCount:
          type: integer
        readyCount:
          type: integer
        totalBytes:
          type: integer
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        visibilitySummary:
          type: string
        mimeSummary:
          type: string
    ProjectUpstreamState:
      type: object
      required:
      - status
      - reasonCode
      properties:
        status:
          type: string
          enum:
          - healthy
          - broken
          - unknown
        reasonCode:
          type: string
          enum:
          - none
          - missing_project_upstream
          - upstream_unreachable
        checkedAt:
          type:
          - string
          - 'null'
          format: date-time
        lastError:
          type:
          - string
          - 'null'
    ProjectRoute:
      type: object
      required:
      - status
      - reasonCode
      - managed
      - upstream
      properties:
        status:
          type: string
          enum:
          - healthy
          - repairing
          - degraded
          - broken
          - unknown
        reasonCode:
          type: string
          enum:
          - none
          - dns_record_missing
          - dns_propagating
          - domain_binding_missing
          - tls_pending
          - missing_project_upstream
          - upstream_unreachable
          - ingress_unreachable
          - unmanaged_custom_domain
          - scw_mutation_failed
        checkedAt:
          type:
          - string
          - 'null'
          format: date-time
        lastRepairAt:
          type:
          - string
          - 'null'
          format: date-time
        lastError:
          type:
          - string
          - 'null'
        managed:
          type: boolean
        convergenceState:
          type:
          - string
          - 'null'
          enum:
          - recovering
          - exhausted
          - ready
          - null
        upstream:
          $ref: '#/components/schemas/ProjectUpstreamState'
    QuotaBlockResponse:
      type: object
      required:
      - error
      - reason
      - quota
      properties:
        error:
          type: string
          enum:
          - Conflict
        reason:
          type: string
          enum:
          - quota-blocked
        quota:
          type: object
          required:
          - actionCode
          - metricCode
          - used
          - limit
          - resetAt
          - recoveryActions
          properties:
            actionCode:
              type: string
            metricCode:
              type:
              - string
              - 'null'
            used:
              type:
              - string
              - 'null'
              pattern: ^[0-9]+(?:\.[0-9]+)?$
            limit:
              type:
              - string
              - 'null'
              pattern: ^[0-9]+(?:\.[0-9]+)?$
            resetAt:
              type:
              - string
              - 'null'
              format: date-time
            recoveryActions:
              type: array
              items:
                type: string
    StorageObjectMetadataInvalidResponse:
      type: object
      required:
      - error
      - reason
      properties:
        error:
          type: string
          enum:
          - Storage object metadata is invalid
        reason:
          type: string
          enum:
          - storage-object-metadata-invalid
    ProjectServingSuspension:
      type: object
      description: An operator suspension of the project's public serving (ADR 0080). Operator notes and evidence are never included.
      required:
      - state
      - reasonCategory
      - reasonLabel
      - since
      - supportEmail
      - policyUrl
      properties:
        state:
          type: string
          enum:
          - suspended
        reasonCategory:
          type: string
          enum:
          - phishing
          - malware
          - shared_domain_abuse
          - spam
          - illegal_content
          - legal_order
          - other_policy_violation
        reasonLabel:
          type: string
        since:
          type:
          - string
          - 'null'
          format: date-time
        supportEmail:
          type: string
        policyUrl:
          type: string
      additionalProperties: false
    ProjectStorageSnapshot:
      type: object
      required:
      - bucketCount
      - objectCount
      - readyObjectCount
      - pendingObjectCount
      - failedObjectCount
      - imageObjectCount
      - totalBytes
      - visibilitySummary
      - latestObjectUpdatedAt
      properties:
        bucketCount:
          type: integer
        objectCount:
          type: integer
        readyObjectCount:
          type: integer
        pendingObjectCount:
          type: integer
        failedObjectCount:
          type: integer
        imageObjectCount:
          type: integer
        totalBytes:
          type: integer
        visibilitySummary:
          type: string
        latestObjectUpdatedAt:
          type:
          - string
          - 'null'
          format: date-time
    StorageObject:
      type: object
      required:
      - id
      - organizationId
      - projectId
      - createdByUserId
      - logicalKey
      - visibility
      - uploadStatus
      - preview
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        organizationId:
          type: string
        projectId:
          type: string
        bucketId:
          type:
          - string
          - 'null'
        createdByUserId:
          type: string
        logicalKey:
          type: string
        objectKey:
          type:
          - string
          - 'null'
        contentType:
          type:
          - string
          - 'null'
        sizeBytes:
          type:
          - integer
          - 'null'
        visibility:
          type: string
          enum:
          - private
          - public
        uploadStatus:
          type: string
          enum:
          - pending
          - ready
          - failed
          - deleted
        preview:
          type: object
          required:
          - status
          - imageUrl
          - width
          - height
          - actions
          properties:
            status:
              type: string
              enum:
              - loading
              - ready
              - unavailable
              - none
            imageUrl:
              type:
              - string
              - 'null'
              format: uri-reference
            width:
              type:
              - integer
              - 'null'
              minimum: 1
              maximum: 960
            height:
              type:
              - integer
              - 'null'
              minimum: 1
              maximum: 960
            actions:
              type: object
              required:
              - retryPreview
              properties:
                retryPreview:
                  type: boolean
        productUrl:
          type:
          - string
          - 'null'
          format: uri
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    StorageObjectResponse:
      type: object
      required:
      - project
      - storageObject
      properties:
        project:
          $ref: '#/components/schemas/ProjectSummary'
        bucket:
          anyOf:
          - $ref: '#/components/schemas/ProjectStorageBucketSummary'
          - type: 'null'
        snapshot:
          anyOf:
          - $ref: '#/components/schemas/ProjectStorageSnapshot'
          - type: 'null'
        storageObject:
          $ref: '#/components/schemas/StorageObject'
        ok:
          type: boolean
    ProjectSourceProfileSummary:
      type: object
      required:
      - framework
      - frameworkLabel
      - outputMode
      properties:
        framework:
          type: string
          enum:
          - next
          - astro
          - svelte-kit
          - nuxt
          - react-router
          - tanstack-start
          - vite
          - hono
          - nestjs
          - fastify
          - express
          - django
          - fastapi
          - flask
          - laravel
          - rails
          - node
          - python
          - php
          - ruby
          - go
          - java
          - dotnet
          - static
        frameworkLabel:
          type: string
        outputMode:
          type: string
          enum:
          - runtime
          - static
    ProjectSourceLock:
      type: object
      description: 'ADR 0090: while locked, no caller can change the project repository, branch, root directory or deployment mode.'
      required:
      - locked
      - lockedAt
      properties:
        locked:
          type: boolean
        lockedAt:
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
    CreateStorageObjectReadUrlResponse:
      type: object
      required:
      - project
      - storageObject
      - readUrl
      - expiresAt
      properties:
        project:
          $ref: '#/components/schemas/ProjectSummary'
        storageObject:
          $ref: '#/components/schemas/StorageObject'
        readUrl:
          type: string
          format: uri
        expiresAt:
          type: string
          format: date-time
    RetryableStorageBlockerResponse:
      type: object
      required:
      - error
      - reason
      - retryable
      properties:
        error:
          type: string
        reason:
          type: string
          enum:
          - quota-state-unavailable
          - storage-accounting-unavailable
        retryable:
          type: boolean
          enum:
          - true
    ReleaseUsability:
      type: object
      required:
      - status
      - reasonCode
      - lastLiveDeploymentId
      properties:
        status:
          type: string
          enum:
          - reachable
          - degraded
          - blocked
          - unknown
        reasonCode:
          type: string
          enum:
          - none
          - missing_live_release
          - access_not_allowed
          - route_repair_in_progress
          - route_incident
          - project_suspended
        lastLiveDeploymentId:
          type:
          - string
          - 'null'
    ProjectSummaryStatus:
      type: object
      required:
      - label
      - tone
      - code
      - detailTitle
      - detail
      properties:
        label:
          type: string
        tone:
          type: string
          enum:
          - neutral
          - problem
          - error
        code:
          type: string
          enum:
          - setup_required
          - route_issue
          - deploy_failed
          - deploy_unhealthy
          - live_release_blocked
          - status_check_delayed
          - deploy_in_progress
          - rollback_live
          - healthy
          - suspended
        detailTitle:
          type:
          - string
          - 'null'
        detail:
          type:
          - string
          - 'null'
    ProjectSummary:
      type: object
      required:
      - id
      - deploymentMode
      - projectRoute
      - releaseUsability
      - sourceProfile
      properties:
        id:
          type: string
        name:
          type:
          - string
          - 'null'
        organizationId:
          type:
          - string
          - 'null'
        projectMembershipId:
          type:
          - string
          - 'null'
        projectRole:
          type:
          - string
          - 'null'
          enum:
          - owner
          - admin
          - contributor
          - null
        projectSlug:
          type:
          - string
          - 'null'
        projectHostname:
          type:
          - string
          - 'null'
        primaryHostname:
          type:
          - string
          - 'null'
          description: 'Official address of the project: its active custom domain whose DNS points at Eurobase, the one that went live first when several do, otherwise projectHostname. projectHostname stays reserved and keeps serving.'
        deploymentMode:
          type: string
          enum:
          - runtime
          - static
        lifecycleState:
          type:
          - string
          - 'null'
        deleteRequestedAt:
          type:
          - string
          - 'null'
          format: date-time
        projectRoute:
          $ref: '#/components/schemas/ProjectRoute'
        releaseUsability:
          $ref: '#/components/schemas/ReleaseUsability'
        projectSummaryStatus:
          $ref: '#/components/schemas/ProjectSummaryStatus'
        servingSuspension:
          oneOf:
          - $ref: '#/components/schemas/ProjectServingSuspension'
          - type: 'null'
        sourceProfile:
          oneOf:
          - $ref: '#/components/schemas/ProjectSourceProfileSummary'
          - type: 'null'
        sourceLock:
          $ref: '#/components/schemas/ProjectSourceLock'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Host-eurobase_session
    csrfHeader:
      type: apiKey
      in: header
      name: X-Eurobase-CSRF