ASAP Settings API

openapi: 3.2.0
info:
  title: ASAP Platform Settings API
  description: 'Public HTTP API for ASAP Platform (api.asap.cool).


    All `/v1` responses are wrapped in a standard envelope. Success responses are `{ "data": , "meta": { "request_id", "next_cursor"?, "has_more"? } }` — the schema documented for each operation describes the inner `data` value. Errors are `{ "error": { "code", "message", "field"?, "request_id" } }`. Every response also carries an `X-Request-Id` header matching `meta.request_id` / `error.request_id`.'
  license:
    name: BUSL-1.1
  version: 0.0.0
servers:
- url: https://api.asap.cool
  description: Production
tags:
- name: Settings
  description: 'User self-service: data export and account deletion.'
paths:
  /v1/public/account/deletion/cancel:
    get:
      tags:
      - Settings
      summary: '`GET /v1/public/account/deletion/cancel`'
      description: 'Renders a confirmation form and changes nothing: mail clients and link

        scanners prefetch links, and a `GET` that cancelled would silently undo a

        deletion the person may still want.'
      operationId: accountDeletionCancelPage
      parameters:
      - name: token
        in: query
        description: Signed token from the email link.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Confirmation form.
          content:
            text/html: {}
        '400':
          description: Invalid or expired token.
          content:
            text/html: {}
    post:
      tags:
      - Settings
      summary: '`POST /v1/public/account/deletion/cancel`'
      description: 'Form submit of [`cancel_page`]. Calls off the deletion the token was issued

        for; idempotent.'
      operationId: accountDeletionCancel
      parameters:
      - name: token
        in: query
        description: Signed token from the email link.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletion cancelled, or nothing was pending.
          content:
            text/html: {}
        '400':
          description: Invalid or expired token.
          content:
            text/html: {}
        '503':
          description: Could not be recorded; nothing changed.
  /v1/settings/account/delete:
    post:
      tags:
      - Settings
      summary: '`POST /v1/settings/account/delete`'
      description: 'Schedules the erasure 30 days out, revokes every session of the caller and

        emails the cancellation link. Asking again while a deletion is pending

        returns the existing deadline and changes nothing.


        Refuses (409 `owner_transfer_required`) when the caller is the sole Owner

        of an org that still has other members, so the UI can guide them to

        promote a co-owner first.


        # Errors


        [`AuthRouteError::Validation`] when `confirm` is not `"DELETE"`,

        [`AuthRouteError::Unauthenticated`] for API-key callers,

        [`AuthRouteError::OwnerTransferRequired`] when an org is blocked,

        [`AuthRouteError::Internal`] on database failure.'
      operationId: request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAccountRequest'
        required: true
      responses:
        '200':
          description: Deletion scheduled; every session was revoked and the auth cookies expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletionScheduled'
        '401':
          description: Not authenticated or API-key caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: Caller is sole Owner of orgs with other members; transfer required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerTransferBody'
        '422':
          description: '`confirm` must equal `"DELETE"`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/settings/account/delete/cancel:
    post:
      tags:
      - Settings
      summary: '`POST /v1/settings/account/delete/cancel`'
      description: 'Calls off a pending deletion of the signed-in account. Idempotent: with

        nothing pending it answers 204 as well.


        # Errors


        [`AuthRouteError::Unauthenticated`] for API-key callers,

        [`AuthRouteError::Conflict`] when the grace period is already over,

        [`AuthRouteError::Internal`] on database failure.'
      operationId: cancel_request
      responses:
        '204':
          description: No deletion is pending any more.
        '401':
          description: Not authenticated or API-key caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: The grace period is over; the erasure is under way.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/settings/account/export:
    get:
      tags:
      - Settings
      summary: '`GET /v1/settings/account/export`'
      description: 'Returns `asap-account-export.zip` (`export.json`, the profile photo when

        there is one, `README.txt`) as an attachment.


        # Errors


        Returns [`AuthRouteError::Unauthenticated`] for API-key callers

        (this endpoint is session-only) or when the user row has been

        deleted underneath an active session; [`AuthRouteError::Internal`]

        for any database, storage or serialization failure.'
      operationId: export
      responses:
        '200':
          description: 'ZIP archive of the user''s data (attachment): export.json, the profile photo, README.txt.'
          content:
            application/zip: {}
        '401':
          description: Not authenticated or API-key caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
components:
  schemas:
    ErrorBody:
      type: object
      description: 'Generic error body returned by API handlers when they fail. `code` is a

        stable machine-readable token; `message` is human-friendly and meant for

        surfacing to end users.'
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine token (e.g. `invalid_credentials`).
        field:
          type:
          - string
          - 'null'
          description: Offending request field for validation errors, when known.
        message:
          type: string
          description: Human-readable message.
    OwnerTransferBody:
      type: object
      description: '409 body for `owner_transfer_required`. Lists every org blocking the

        account deletion so the UI can guide the user.'
      required:
      - code
      - message
      - blocking_orgs
      properties:
        blocking_orgs:
          type: array
          items:
            $ref: '#/components/schemas/BlockingOrg'
          description: Orgs that block the deletion.
        code:
          type: string
          description: Always `"owner_transfer_required"`.
        message:
          type: string
          description: Human-readable message.
    DeleteAccountRequest:
      type: object
      description: Body of `POST /v1/settings/account/delete`.
      required:
      - confirm
      properties:
        confirm:
          type: string
          description: 'Must be the literal string `"DELETE"`. The frontend asks the

            user to type the word as a confirmation step.'
    BlockingOrg:
      type: object
      description: 'Org that blocks account deletion because the caller is its sole

        Owner and other members still belong to it.


        Serialized as one entry of the `blocking_orgs` array in the 409

        response body shaped by [`ApiError::OwnerTransferRequired`].'
      required:
      - org_id
      - slug
      - name
      - other_members
      properties:
        name:
          type: string
          description: Human-readable name.
        org_id:
          type: string
          format: uuid
          description: Organization id.
        other_members:
          type: integer
          format: int64
          description: Count of members other than the caller still attached to the org.
        slug:
          type: string
          description: URL-safe slug.
    DeletionScheduled:
      type: object
      description: A deletion waiting for its deadline.
      required:
      - delete_after
      properties:
        delete_after:
          type: string
          format: date-time
          description: When the account will be erased unless the request is cancelled.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
    session:
      type: apiKey
      in: cookie
      name: asap_session