openapi: 3.0.3
info:
  title: Form.taxi Create Endpoint API
  description: >
    API for Form.taxi - a GDPR-compliant form backend service.
    This endpoint allows tools and AI agents to programmatically create
    a form endpoint without prior authentication.
  version: 1.0.0
  contact:
    url: https://form.taxi
servers:
  - url: https://form.taxi/api/v1
    description: Production

paths:
  /create-endpoint:
    post:
      operationId: createEndpoint
      summary: Create a new form endpoint
      description: >
        Creates a new user account (if the email is not yet registered) and a
        form endpoint. Returns the endpoint URL that can be used as the action
        attribute of an HTML form. No authentication required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndpointRequest'
            example:
              email: user@example.com
              form_name: Contact Form
              website_url: https://example.com
              language: en
              timezone: Europe/Vienna
      responses:
        '201':
          description: Endpoint successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEndpointResponse'
              example:
                success: true
                endpoint_url: https://form.taxi/s/xxxxxxxx
        '400':
          description: Content incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentError'
              example:
                error: content_error
                message: Invalid JSON.
        '409':
          description: Email address already registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailExistsError'
              example:
                success: false
                error: email_exists
                message: 'This email address is already registered. Please log in to create an endpoint: https://form.taxi/panel/login'
        '415':
          description: Content-Type incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentTypeError'
              example:
                error: contenttype_error
                message: Content-Type "application/json" required.
        '422':
          description: Validation error - required field missing or invalid value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                error: validation_error
                message: Email address is required.

components:
  schemas:
    CreateEndpointRequest:
      type: object
      required:
        - email
        - form_name
        - language
      properties:
        email:
          type: string
          format: email
          description: >
            Email address used as the destination for form submissions and as
            the username for the new account.
          example: user@example.com
        form_name:
          type: string
          description: Name of the form (e.g. "Contact Form").
          example: Contact Form
        website_url:
          type: string
          format: uri
          description: URL of the website where the form will be used (optional).
          example: https://example.com
        language:
          type: string
          enum:
            - de
            - en
          description: Language for the account and email notifications.
          example: en
        timezone:
          type: string
          description: >
            IANA time zone identifier (optional). Defaults to UTC if not
            provided.
          example: Europe/Vienna

    CreateEndpointResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was executed successfully.
        endpoint_url:
          type: string
          format: uri
          description: >
            The form endpoint URL. Use this as the action attribute of your
            HTML form.
          example: https://form.taxi/s/xxxxxxxx

    EmailExistsError:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was executed successfully.
        error:
          type: string
          enum:
            - email_exists
        message:
          type: string

    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was executed successfully.
        error:
          type: string
          enum:
            - validation_error
        message:
          type: string

    ContentTypeError:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was executed successfully.
        error:
          type: string
          enum:
            - contenttype_error
        message:
          type: string

    ContentError:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was executed successfully.
        error:
          type: string
          enum:
            - content_error
        message:
          type: string