openapi: 3.0.3
info:
  title: Albato Embedded API
  description: >-
    REST API for Albato Embedded iPaaS, enabling SaaS companies to integrate
    Albato's automation capabilities into their products. Manage teams, users,
    connectors, and white-label automation flows for end customers.
  version: 1.0.0
  contact:
    name: Albato Support
    url: https://albato.com/embedded
servers:
  - url: https://albato.com/api/v1/embedded
    description: Albato Embedded API
security:
  - ApiKeyAuth: []
tags:
  - name: Teams
    description: Manage embedded teams (customer accounts)
  - name: Users
    description: Manage team users
  - name: Connectors
    description: Manage app connectors
  - name: Templates
    description: Manage automation templates
paths:
  /teams:
    get:
      operationId: listTeams
      summary: List teams
      description: Returns all embedded teams (customer accounts).
      tags:
        - Teams
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of teams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamList'
        '401':
          description: Unauthorized
    post:
      operationId: createTeam
      summary: Create a team
      description: Creates a new embedded team for a customer account.
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamRequest'
      responses:
        '201':
          description: Team created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
  /teams/{id}:
    get:
      operationId: getTeam
      summary: Get a team
      description: Returns details for a specific team.
      tags:
        - Teams
      parameters:
        - name: id
          in: path
          required: true
          description: Team ID
          schema:
            type: string
      responses:
        '200':
          description: Team details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    put:
      operationId: updateTeam
      summary: Update a team
      description: Updates an existing team.
      tags:
        - Teams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamRequest'
      responses:
        '200':
          description: Team updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
    delete:
      operationId: deleteTeam
      summary: Delete a team
      description: Deletes a team and all associated resources.
      tags:
        - Teams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
  /teams/{teamId}/users:
    get:
      operationId: listTeamUsers
      summary: List team users
      description: Returns users for a specific team.
      tags:
        - Users
      parameters:
        - name: teamId
          in: path
          required: true
          description: Team ID
          schema:
            type: string
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
    post:
      operationId: createTeamUser
      summary: Create a team user
      description: Adds a new user to a team.
      tags:
        - Users
      parameters:
        - name: teamId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /connectors:
    get:
      operationId: listConnectors
      summary: List connectors
      description: Returns all available app connectors for embedded use.
      tags:
        - Connectors
      parameters:
        - name: search
          in: query
          description: Search by connector name
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: List of connectors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorList'
  /templates:
    get:
      operationId: listTemplates
      summary: List templates
      description: Returns automation templates available for embedded use.
      tags:
        - Templates
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
    post:
      operationId: createTemplate
      summary: Create a template
      description: Creates a new automation template for embedded users.
      tags:
        - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateRequest'
      responses:
        '201':
          description: Template created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    TeamRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Team display name
        external_id:
          type: string
          description: External identifier from your system
        plan:
          type: string
          description: Plan identifier for this team
    Team:
      allOf:
        - $ref: '#/components/schemas/TeamRequest'
        - type: object
          properties:
            id:
              type: string
            active_automations:
              type: integer
            transaction_count:
              type: integer
            created_at:
              type: string
              format: date-time
    TeamList:
      type: object
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Team'
    UserRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        role:
          type: string
          enum: [admin, member]
    User:
      allOf:
        - $ref: '#/components/schemas/UserRequest'
        - type: object
          properties:
            id:
              type: string
            team_id:
              type: string
            created_at:
              type: string
              format: date-time
    UserList:
      type: object
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Connector:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        category:
          type: string
        description:
          type: string
        triggers_count:
          type: integer
        actions_count:
          type: integer
        icon_url:
          type: string
          format: uri
    ConnectorList:
      type: object
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Connector'
    TemplateRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        category:
          type: string
        steps:
          type: array
          items:
            type: object
    Template:
      allOf:
        - $ref: '#/components/schemas/TemplateRequest'
        - type: object
          properties:
            id:
              type: string
            created_at:
              type: string
              format: date-time
    TemplateList:
      type: object
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Template'