openapi: 3.1.0
info:
  title: Cyclr Accounts API
  description: 'Cyclr''s REST API allows you to manage your Accounts and Cycles, as well as install Templates and Connectors. The API is divided into two parts: Partner Level and Account Level. You can use the same OAuth Access Token for both, but Account level endpoints require an additional X-Cyclr-Account HTTP header to identify which Cyclr Account to execute the call against.'
  version: 1.0.0
  contact:
    name: Cyclr
    url: https://cyclr.com
  license:
    name: Proprietary
    url: https://cyclr.com/legal
servers:
- url: https://api.cyclr.com/v1.0
  description: Cyclr US API
- url: https://api.eu.cyclr.com/v1.0
  description: Cyclr EU API
- url: https://api.au.cyclr.com/v1.0
  description: Cyclr AU API
security:
- bearerAuth: []
tags:
- name: Accounts
  description: Manage Cyclr accounts
paths:
  /accounts:
    get:
      operationId: listAccounts
      summary: Cyclr List Accounts
      description: Retrieve a list of all Cyclr accounts under the partner.
      tags:
      - Accounts
      parameters:
      - name: page
        in: query
        schema:
          type: integer
        description: Page number for pagination
      - name: pageSize
        in: query
        schema:
          type: integer
        description: Number of results per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
    post:
      operationId: createAccount
      summary: Cyclr Create Account
      description: Create a new Cyclr account under the partner.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
      responses:
        '200':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Cyclr Get Account
      description: Retrieve details of a specific Cyclr account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
    put:
      operationId: updateAccount
      summary: Cyclr Update Account
      description: Update an existing Cyclr account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
      responses:
        '200':
          description: Account updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
        '404':
          description: Account not found
    delete:
      operationId: deleteAccount
      summary: Cyclr Delete Account
      description: Delete a specific Cyclr account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Account deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Account not found
  /accounts/{accountId}/signintoken:
    post:
      operationId: getAccountSignInToken
      summary: Cyclr Get Account Sign-In Token
      description: Generate a sign-in token for a specific account, allowing access to the Cyclr console for that account.
      tags:
      - Accounts
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Sign-in token generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  Token:
                    type: string
                    description: The sign-in token
                  ExpiresAtUtc:
                    type: string
                    format: date-time
                    description: Token expiry time in UTC
        '401':
          description: Unauthorized
        '404':
          description: Account not found
components:
  schemas:
    InstalledConnector:
      type: object
      properties:
        Id:
          type: integer
          description: Installed connector identifier
        Name:
          type: string
          description: Installed connector name
        Description:
          type: string
          description: Installed connector description
        ConnectorId:
          type: integer
          description: Reference to the base connector
        Authenticated:
          type: boolean
          description: Whether the connector has been authenticated
        Status:
          type: string
          description: Installation status
    AccountCreate:
      type: object
      required:
      - Name
      properties:
        Name:
          type: string
          description: Account name
        Description:
          type: string
          description: Account description
        ApiId:
          type: string
          description: External API identifier for the account
    Account:
      type: object
      properties:
        Id:
          type: string
          description: Unique account identifier
        Name:
          type: string
          description: Account name
        Description:
          type: string
          description: Account description
        AudienceCount:
          type: integer
          description: Number of audiences in the account
        CreatedDate:
          type: string
          format: date-time
          description: When the account was created
        Connectors:
          type: array
          description: Connectors installed in the account
          items:
            $ref: '#/components/schemas/InstalledConnector'
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
      description: The unique identifier of the Cyclr account
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token obtained from the /oauth/token endpoint using Client Credentials flow with your Cyclr Console Client ID and Client Secret.