Cycloid Organization Children API

openapi: 3.2.0
info:
  description: This is the Cycloid's API Reference. It provides descriptions, syntax, and usage examples for each of the actions and data types available within our console.
  title: Welcome! Organization Children API
  termsOfService: https://console.cycloid.io/terms
  contact:
    name: The Great Owl
    url: https://www.cycloid.io
    email: contact@cycloid.io
  license:
    name: Cycloid @copyrights
    url: https://cycloid.io
  version: '0'
servers:
- url: https://http-api.cycloid.io
security:
- api_key: []
- api_key_query: []
tags:
- description: Operations on the children of an organization
  name: Organization Children
paths:
  /organizations/{organization_canonical}/children:
    get:
      description: Get the children organizations that the authenticated user has access.
      tags:
      - Organization Children
      operationId: getChildren
      parameters:
      - $ref: '#/components/parameters/organization_canonical'
      - $ref: '#/components/parameters/page_index'
      - $ref: '#/components/parameters/page_size'
      - description: Search by the organization's name
        name: organization_name
        in: query
        schema:
          type: string
      - description: Search by organization's creation date
        name: organization_created_at
        in: query
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/order_by_query'
      responses:
        '200':
          description: List of the children organizations which the authenticated user has access.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                - blocked: null
                  canonical: org1
                  ci_team_name: asfdOPNljk
                  created_at: 1503225026
                  has_children: true
                  id: 1
                  name: Organization 1
                  updated_at: 1503335026
                - blocked: null
                  canonical: org2
                  ci_team_name: asfdOPNljk
                  created_at: 1501131026
                  has_children: false
                  id: 1
                  name: Organization 2
                  updated_at: 1503333026
                - blocked: null
                  canonical: org3
                  ci_team_name: asfdOPNljk
                  created_at: 1500135021
                  has_children: false
                  id: 1
                  name: Organization 3
                  updated_at: 1503332021
                pagination:
                  index: 1
                  size: 10
                  total: 3
        '403':
          $ref: '#/components/responses/not_enough_permissions'
        '404':
          $ref: '#/components/responses/not_found_entity_in_path'
        '422':
          $ref: '#/components/responses/unprocessable_entity'
        default:
          $ref: '#/components/responses/unexpected_error'
      summary: Get children
      x-summary-source: derived
    post:
      description: Create a new organization child, making the authenticated user the owner of it.
      tags:
      - Organization Children
      operationId: createChild
      parameters:
      - $ref: '#/components/parameters/organization_canonical'
      responses:
        '200':
          description: Organization created. The body contains the information of the new created organization.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Organization'
              example:
                data:
                  blocked: null
                  canonical: org1
                  ci_team_name: asfdOPNljk
                  created_at: 1503225026
                  id: 1
                  name: Organization 1
                  updated_at: 1503335026
      requestBody:
        content:
          application/vnd.cycloid.io.v1+json:
            schema:
              $ref: '#/components/schemas/NewOrganization'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NewOrganization'
        description: The information of the organization to create.
        required: true
      summary: Create child
      x-summary-source: derived
components:
  parameters:
    page_index:
      description: The page number to request. The first page is 1.
      name: page_index
      in: query
      schema:
        type: integer
        format: uint32
        default: 1
    page_size:
      description: The number of items at most which the response can have.
      name: page_size
      in: query
      schema:
        type: integer
        format: uint32
        default: 100
    organization_canonical:
      description: A canonical of an organization.
      name: organization_canonical
      in: path
      required: true
      schema:
        type: string
        maxLength: 100
        minLength: 2
        pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
    order_by_query:
      description: 'Allows to order the list of items. Example usage: field_name:asc. Multiple order_by parameters are allowed, applied in the order they are specified.

        '
      name: order_by
      in: query
      schema:
        type: string
  schemas:
    Subscription:
      description: 'It reflects the relation between an Organization and a Plan which

        could be the Free Trial or others, for more info check https://www.cycloid.io/pricing

        '
      type: object
      title: Subscription
      required:
      - expires_at
      - plan
      properties:
        current_members:
          type: integer
          format: uint64
        expires_at:
          type: integer
          format: uint64
        members_count:
          type: integer
          format: uint64
        plan:
          $ref: '#/components/schemas/SubscriptionPlan'
    SimpleTeam:
      description: The entity which represents the information of a team a bit simplified.
      type: object
      title: SimpleTeam
      required:
      - id
      - canonical
      - name
      - created_at
      - updated_at
      properties:
        canonical:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        created_at:
          type: integer
          format: uint64
        id:
          type: integer
          format: uint32
          minimum: 1
        name:
          type: string
          minLength: 2
        owner:
          description: 'Organization member that owns this team. When a user is the owner of a

            team it has all the permissions on it.

            In the event where the user has been deleted this field might be empty.

            '
          $ref: '#/components/schemas/User'
        updated_at:
          type: integer
          format: uint64
    Role:
      description: Role represents the authorization level that an user has to access to a specific entity of the system. A role contains a list of rules to define the access control. Note not all the entities supports roles access control; see the API endpoints to know which entities support them.
      title: Role access control
      required:
      - id
      - name
      - canonical
      - description
      - rules
      - default
      properties:
        canonical:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        created_at:
          type: integer
          format: uint64
        default:
          type: boolean
        description:
          type: string
        id:
          type: integer
          format: uint32
          minimum: 1
        name:
          type: string
          maxLength: 100
          minLength: 2
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
        updated_at:
          type: integer
          format: uint64
    MemberOrg:
      description: Member is a user who is associated to an organization.
      type: object
      title: Member of an organization
      required:
      - id
      - created_at
      - role
      properties:
        created_at:
          description: When the user became a member.
          type: integer
          format: uint64
        email:
          description: user email
          type: string
          format: email
        full_name:
          type: string
        id:
          type: integer
          format: uint32
          minimum: 1
        invitation_email:
          description: The email address to which the invitation was sent. It's used to resend the invitation.
          type: string
          format: email
        invitation_resent_at:
          type: integer
          format: uint64
        invitation_state:
          type: string
          enum:
          - pending
          - accepted
          - declined
        invited_at:
          description: When the user had been invited to join as a member. When not present, the user is already a member, so she/he has verified her/his invitation.
          type: integer
          format: uint64
        invited_by:
          description: Organization member who invited the current user.
          $ref: '#/components/schemas/SimpleMemberOrg'
        last_login_at:
          description: When the user logged in last time.
          type: integer
          format: uint64
        locale:
          description: User's preferred language
          type: string
          enum:
          - en
          - fr
          - es
        mfa_enabled:
          type: boolean
        picture_url:
          type: string
          format: uri
        role:
          $ref: '#/components/schemas/Role'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/SimpleTeam'
        updated_at:
          description: When the user had the role modified.
          type: integer
          format: uint64
        username:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
    User:
      description: A summary of a user to be used in places where only the basic information are need or are enough.
      type: object
      title: Basic info of a user
      required:
      - id
      - username
      - full_name
      - email
      - locale
      - created_at
      - mfa_enabled
      properties:
        country_code:
          description: Code of a country the user is from in alpha-2 format
          type: string
          pattern: ^[A-Z]{2}$
        created_at:
          description: When the user became a member.
          type: integer
          format: uint64
        email:
          description: User's primary email.
          type: string
          format: email
        full_name:
          type: string
        id:
          type: integer
          format: uint32
          minimum: 1
        last_login_at:
          description: When the user logged in last time.
          type: integer
          format: uint64
        locale:
          description: The local that the user prefer.
          type: string
          pattern: ^[a-z]{2}(?:-[a-z][a-z])?$
        mfa_enabled:
          type: boolean
        picture_url:
          type: string
          format: uri
        updated_at:
          description: When the user had the role modified.
          type: integer
          format: uint64
        username:
          type: string
          maxLength: 30
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
    SimpleMemberOrg:
      description: Simplified model of a member of an organization. The member is 'accepted' and have an associated user account.
      type: object
      title: Simplified model of a member of an organization
      required:
      - id
      - email
      - created_at
      properties:
        created_at:
          description: When the user became a member.
          type: integer
          format: uint64
        email:
          description: Primary email
          type: string
          format: email
        full_name:
          type: string
        id:
          description: Member ID (different from the user ID)
          type: integer
          format: uint32
          minimum: 1
        last_login_at:
          description: When the user logged in last time.
          type: integer
          format: uint64
        picture_url:
          type: string
          format: uri
        updated_at:
          description: When the user had the role modified.
          type: integer
          format: uint64
        username:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
    Organization:
      description: The entity which holds all the direct information attached to an organization.
      type: object
      title: Organization
      required:
      - id
      - canonical
      - ci_team_name
      - ci_url
      - ci_port
      - name
      - is_root
      - can_create_appearance
      - can_children_create_appearance
      - can_use_dedicated_authentication
      - can_children_use_dedicated_authentication
      - can_manage_oidc_mapping
      - can_children_manage_oidc_mapping
      - is_using_dedicated_authentication
      - mfa_enabled
      - blocked
      - has_children
      - created_at
      - updated_at
      properties:
        admins:
          type: array
          items:
            $ref: '#/components/schemas/MemberOrg'
        appearance:
          $ref: '#/components/schemas/Appearance'
        blocked:
          type: array
          items:
            type: string
        can_children_create_appearance:
          type: boolean
        can_children_manage_oidc_mapping:
          type: boolean
        can_children_use_dedicated_authentication:
          type: boolean
        can_create_appearance:
          type: boolean
        can_manage_oidc_mapping:
          type:
          - boolean
          - 'null'
          readOnly: true
        can_use_dedicated_authentication:
          type: boolean
        canonical:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        ci_port:
          type: string
        ci_team_name:
          type: string
        ci_url:
          type: string
        created_at:
          type: integer
          format: uint64
        disable_cost_estimation:
          description: When true, the StackForms cost estimation panel is hidden on every organization of the platform. Set on the root organization and applied platform-wide, so it is only returned for the root organization.
          type:
          - boolean
          - 'null'
        disable_member_invitation_email:
          description: When true, adding a member to an organization sends no invitation email. Set on the root organization and applied platform-wide, so it is only returned for the root organization.
          type:
          - boolean
          - 'null'
        disable_signup:
          description: When true, signups are rejected everywhere on the platform (plain email/password, AWS Marketplace, and SSO/social auto-enrollment) unless the email is already invited — same gate as sso_invite_only. Set on the root organization and applied platform-wide, so it is only returned for the root organization.
          type:
          - boolean
          - 'null'
        has_children:
          type: boolean
        hide_stack_version_out_of_sync:
          description: When true, the component list and project list hide the indicator shown when a version's commit no longer matches its reference commit. Other version status indicators are unaffected.
          type: boolean
        id:
          type: integer
          format: uint32
          minimum: 1
        impersonation_emails:
          description: Emails of the users allowed to impersonate other users. Set on the root organization only; empty means nobody can impersonate. Only returned to callers allowed to update the organization, omitted for everyone else.
          type:
          - array
          - 'null'
          maxItems: 100
          items:
            type: string
            maxLength: 255
            pattern: ^\S+@\S+\.\S+$
        is_root:
          description: Defines if this organization is the root one on the platform or not
          type: boolean
        is_using_dedicated_authentication:
          type: boolean
        mfa_enabled:
          type: boolean
        name:
          type: string
          minLength: 2
        parent_canonical:
          description: Canonical of the immediate parent organization. Omitted when this organization is root.
          type:
          - string
          - 'null'
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        parent_name:
          description: Display name of the immediate parent organization. Omitted when this organization is root.
          type:
          - string
          - 'null'
        sso_invite_only:
          description: When true, SSO users can only join the organization if they have been explicitly invited
          type:
          - boolean
          - 'null'
        stack_branch_exclude_patterns:
          description: Glob patterns (filepath.Match syntax). Versions matching any of these are hidden from non-team-member users.
          type:
          - array
          - 'null'
          maxItems: 50
          items:
            type: string
            maxLength: 200
        stack_branch_include_patterns:
          description: Glob patterns (filepath.Match syntax). When set, only versions whose name matches at least one pattern are shown to non-team-member users. Empty means show all.
          type:
          - array
          - 'null'
          maxItems: 50
          items:
            type: string
            maxLength: 200
        subscription:
          $ref: '#/components/schemas/Subscription'
        updated_at:
          type: integer
          format: uint64
    Rule:
      description: Rules define the specific access to the platform
      title: Rule
      required:
      - id
      - effect
      - action
      properties:
        action:
          description: It can be the normal Policy.Code or contain globs like `*` or `**`
          type: string
        effect:
          type: string
          enum:
          - allow
        id:
          description: This is the id of the row from the database, but for blocking organizations we generate rules that are not in the database. When this happens the id is allowed to be 0.
          type: integer
          format: uint32
        resources:
          description: It is the list of resources in which this Rule applies to, the format of it is the one on the Policy.Code but with the `canonical` of the entities like `organization:org-can:team:team-can` for an action of `organization:team:read`
          type: array
          items:
            type: string
    Appearance:
      description: An Appearance holds the values of the branding configuration, which are rendered across an organization
      title: Appearance
      required:
      - canonical
      - name
      - display_name
      - tab_title
      - color
      - logo
      - favicon
      - footer
      properties:
        canonical:
          type: string
          maxLength: 100
          minLength: 1
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        color:
          type: object
          required:
          - r
          - g
          - b
          properties:
            b:
              description: Blue color value of the RGB color
              type: integer
              format: uint32
              maximum: 255
            g:
              description: Green color value of the RGB color
              type: integer
              format: uint32
              maximum: 255
            r:
              description: Red color value of the RGB color
              type: integer
              format: uint32
              maximum: 255
        created_at:
          type: integer
          format: uint64
        display_name:
          type: string
          maxLength: 50
          minLength: 1
        favicon:
          type: string
          format: uri
        footer:
          type: string
          maxLength: 1000
        is_active:
          type: boolean
        logo:
          type: string
          format: uri
        name:
          type: string
          maxLength: 50
          minLength: 1
        tab_title:
          type: string
          maxLength: 50
          minLength: 1
        updated_at:
          type: integer
          format: uint64
    NewOrganization:
      description: The entity which represents a new organization to create in the application.
      type: object
      title: Create Organization
      required:
      - name
      properties:
        canonical:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        name:
          type: string
          minLength: 2
    Pagination:
      type: object
      title: Pagination
      required:
      - total
      - index
      - size
      properties:
        index:
          description: The index of the page sent (the first page is 1).
          type: integer
          format: uint64
          minimum: 1
        size:
          description: The size of the page (the number of entities per page)
          type: integer
          format: uint64
        total:
          description: The total number of items.
          type: integer
          format: uint64
    SubscriptionPlan:
      description: It reflects the Plan used for the subscription
      type: object
      title: SubscriptionPlan
      required:
      - name
      - canonical
      properties:
        canonical:
          type: string
          maxLength: 100
          minLength: 2
          pattern: ^[a-z0-9]([a-z0-9\-_]*[a-z0-9])?$
        name:
          type: string
          minLength: 2
    ErrorPayload:
      description: 'The payload used by the server to response to the client with an Error, those errors could be any of the ones listed [here](https://github.com/cycloidio/youdeploy-http-api/blob/develop/errors/code.go#L10), only the CODE of the error is the one that is guaranteed to not change between the same major version, the MESSAGE could change.

        '
      title: Error Payload
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailsItem'
        request_id:
          type: string
    ErrorDetailsItem:
      description: Represents an item of the list of details of an error.
      title: Error details item
      required:
      - message
      - code
      properties:
        code:
          type: string
        details:
          type: array
          items:
            type: string
        message:
          type: string
  responses:
    not_enough_permissions:
      description: The authenticated user cannot perform the operation because, it doesn't have permissions for such operation.
      headers:
        Content-Length:
          description: The length of the response body in octets (8-bit bytes).
          schema:
            type: integer
            format: uint64
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
          example:
            errors:
            - code: Unauthorized
              message: Not enough permissions to perform the operation
    unprocessable_entity:
      description: All the custom errors that are generated from the Cycloid API
      headers:
        Content-Length:
          description: The length of the response body in octets (8-bit bytes).
          schema:
            type: integer
            format: uint64
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
          example:
            errors:
            - code: SomeCode
              message: some error
    not_found_entity_in_path:
      description: The response sent when any of the entities present in the path is not found.
      headers:
        Content-Length:
          description: The length of the response body in octets (8-bit bytes).
          schema:
            type: integer
            format: uint64
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
          example:
            errors:
            - code: NotFoundEntity
              message: Entity not found
    unexpected_error:
      description: The response sent when an unexpected error happened, as known as an internal server error.
      headers:
        Content-Length:
          description: The length of the response body in octets (8-bit bytes).
          schema:
            type: integer
            format: uint64
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
          example:
            errors:
            - code: Unexpected
              message: Server Internal error
  securitySchemes:
    api_key:
      description: The API authorization is done with JWT tokens
      type: apiKey
      name: Authorization
      in: header
    api_key_query:
      description: The API authorization is done with JWT tokens in the query string
      type: apiKey
      name: api_key
      in: query