AIfra Remote API

openapi: 3.2.0
info:
  title: AIfra preview Remote API
  version: 0.5.0-stage5
  description: SaaS for prebuilt static ZIP previews with server-enforced 48-hour expiry. Availability is announced on the platform website. Production uses isolated per-preview origins; the server never builds or executes user code.
servers:
- url: '{apiOrigin}'
  variables:
    apiOrigin:
      default: https://api.aifra.ru
tags:
- name: Remote
paths:
  /remote/aliases/{alias}:
    get:
      summary: Check a public name without reserving it
      parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
          minLength: 3
          maxLength: 48
      responses:
        '200':
          description: Normalized alias, availability and viewer URL. Reservation happens atomically at publication; used names are never reissued.
        '400':
          description: Invalid or reserved name
        '429':
          description: Rate limit
      tags:
      - Remote
      operationId: getRemoteAliasesByAlias
      x-operation-id-source: derived
  /remote/session:
    get:
      summary: Browser-only short-lived CSRF session
      description: Same-origin approval UI only. Sets host-only HttpOnly SameSite=Strict cookie (Secure in production). Not an agent tool.
      responses:
        '200':
          description: CSRF nonce; no-store
      tags:
      - Remote
      operationId: getRemoteSession
      x-operation-id-source: derived
  /remote/operations/{id}:
    get:
      summary: Read a remote operation receipt
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^rop_[A-Za-z0-9_-]{43}$
      responses:
        '200':
          description: Pending/uncertain/complete/failed/expired, file metadata and public result. Only complete with result.url is a published preview. Share result.url and expires_at, never approval_url or the management key. The browser UI can copy a recipient message or generate a local QR code from that public URL. No archive, management key or source IP.
        '404':
          description: Unknown or purged operation
      tags:
      - Remote
      operationId: getRemoteOperationsById
      x-operation-id-source: derived
  /remote/operations/{id}/confirm:
    post:
      summary: Browser-only explicit approval; never call from an agent
      description: Requires exact Origin, Sec-Fetch-Site same-origin, X-Aifra-Csrf matching the host cookie and a private browser-generated management key in Authorization. Consumes a pending request once. Actual socket/trusted-ingress IP supplies create quota. Terms version must match current. Ambiguous results must not be retried.
      security:
      - managementToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^rop_[A-Za-z0-9_-]{43}$
      - name: X-Aifra-Csrf
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - digest
              - terms_version
              - accept_terms
              - anonymous_id
              properties:
                alias:
                  type: string
                  minLength: 3
                  maxLength: 48
                  description: Optional on create only. Normalized to lowercase ASCII letters, digits and inner hyphens; system names reserved. Omit for random URL. Not a private link.
                digest:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                terms_version:
                  type: string
                  maxLength: 100
                accept_terms:
                  type: boolean
                  const: true
                anonymous_id:
                  type: string
                  pattern: ^aid_[A-Za-z0-9_-]{20,96}$
      responses:
        '200':
          description: Public receipt only
        '400':
          description: Current terms not accepted
        '401':
          description: Wrong management key
        '403':
          description: CSRF/Origin failure
        '404':
          description: Unknown operation
        '409':
          description: Expired, claimed or wrong digest; preview_alias_unavailable alone allows manual retry with another name without reupload. Never replay uncertain results.
        '429':
          description: Quota or rate limit
      tags:
      - Remote
      operationId: postRemoteOperationsByIdConfirm
      x-operation-id-source: derived
components:
  securitySchemes:
    managementToken:
      type: http
      scheme: bearer
      bearerFormat: pmt_*
x-legal:
  terms_path: /legal/terms/
  privacy_path: /legal/privacy/
  retention_path: /legal/retention/
  abuse_path: /abuse/
  path_origin: SITE_ORIGIN (platform website, not API or user-content origin)
  terms_version: 2026-09-23-v3
  acceptance: Explicit accept_terms on create/update; not personal-data consent
  activation: TERMS_VERSION must match the reviewed document before public beta
x-technical-retention:
  version: 2026-09-23-v3
  remoteApprovalSeconds: 7200
  remoteReceiptSeconds: 3600
  rateLimitHours: 25
  lifecycleDays: 30
  adminAuditDays: 90
  backupMaxHours: 48
  supportAfterResolutionDays: 30
  abuseAfterResolutionDays: 90
x-agent-workflow:
  documentation_path: /docs/agent/
  path_origin: SITE_ORIGIN, not the API or preview origin
  input: Prebuilt browser-only static ZIP with index.html at archive root
  acceptance: Obtain explicit terms acceptance before create/update
  output: Return viewer url and expires_at; keep manage_token in private local state
  retries: Do not blindly retry POST after an uncertain network result; creation has no idempotency key
  discovery: Instruction files aid use; no unaided model selection rate is claimed
  unavailable:
  - server-side builds
  - user backend execution
x-preview-constraints:
  ttlHours: 48
  activePreviewsPerIp: 3
  uploadBytes: 52428800
  extractedBytes: 52428800
  activeBytesPerIp: 157286400
  staticOnly: true
  updateExtendsExpiry: false
x-remote-mcp:
  endpoint: https://api.aifra.ru/mcp
  publication: browser_confirmation_required
  approval_ttl_seconds: 7200
  receipt_retention_seconds: 3600
  receipt_retention_starts: completion_or_approval_expiry
  named_links: Optional browser-selected name on create; never reissued; random isolated asset origin is unchanged
  management: Private browser key; never an MCP parameter or result