Covatic

Covatic Users API

The Users API from Covatic — 9 operation(s) for users.

GitHub OpenAPI
Business capability
Identity & Access Management BC-620.20

Operations 9

GET /api/v1/user/clients Get All Companies #
POST /api/v1/user/list Get Company Users #
PUT /api/v1/user/clients/default/{default_client_id} Update Default Client #
POST /api/v1/user/company/default Update Default Company #
POST /api/v1/user/update-user-association Update User Association #
POST /api/v1/user/create-users-with-roles Create Users With Roles #
POST /api/v1/user/resend-invite Resend Invite #
DELETE /api/v1/user/delete/{user_cognito_id} Delete User #
PUT /api/v1/user/update Update User #

Documentation

📖
APIReference
https://prodaudiencebuilderapi.covatic.io/docs
📖
Documentation
https://prodaudiencebuilderapi.covatic.io/redoc
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/covatic/refs/heads/main/authentication/covatic-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/covatic/refs/heads/main/rate-limits/covatic-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/covatic/refs/heads/main/openapi/covatic-users-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/covatic/refs/heads/main/conventions/covatic-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/covatic/refs/heads/main/errors/covatic-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/covatic/refs/heads/main/data-model/covatic-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/covatic-users-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

covatic-users-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Audience builder Users API
  summary: Audience builder is an app for clients to create their campaigns.
  version: 0.0.1
tags:
- name: Users
paths:
  /api/v1/user/clients:
    get:
      tags:
      - Users
      summary: Get All Companies
      operationId: get_all_companies_api_v1_user_clients_get
      security:
      - HTTPBearer: []
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 3
            maxLength: 20
          - type: 'null'
          title: Search tag
          description: Query string to search the company
        description: Query string to search the company
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Page size
          default: 50
          title: Size
        description: Page size
      responses:
        '200':
          description: All clients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Company_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/user/list:
    post:
      tags:
      - Users
      summary: Get Company Users
      operationId: get_company_users_api_v1_user_list_post
      security:
      - HTTPBearer: []
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 3
            maxLength: 20
          - type: 'null'
          title: Search tag
          description: Query string to search the user in a company
        description: Query string to search the user in a company
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Page size
          default: 50
          title: Size
        description: Page size
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyRequest'
      responses:
        '200':
          description: All Company users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_Any_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/user/clients/default/{default_client_id}:
    put:
      tags:
      - Users
      summary: Update Default Client
      operationId: update_default_client_api_v1_user_clients_default__default_client_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: default_client_id
        in: path
        required: true
        schema:
          type: string
          example: 5eb7cf5a86d9755df3a6c593
          title: Default Client Id
      responses:
        '200':
          description: Client updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models__profile__Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/user/company/default:
    post:
      tags:
      - Users
      summary: Update Default Company
      operationId: update_default_company_api_v1_user_company_default_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreateUsersRequest'
        required: true
      responses:
        '200':
          description: Client updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models__profile__Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/user/update-user-association:
    post:
      tags:
      - Users
      summary: Update User Association
      operationId: update_user_association_api_v1_user_update_user_association_post
      security:
      - HTTPBearer: []
      parameters:
      - name: parent_type
        in: query
        required: true
        schema:
          type: string
          maxLength: 50
          title: Parent Type
        examples:
          Octave:
            value: company
          Bauer UK:
            value: sub-company
          News UK:
            value: sub-company
      - name: parent_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 50
          title: Parent Name
        examples:
          Octave:
            value: Octave
          Bauer UK:
            value: Bauer UK
          News UK:
            value: News UK
      - name: client_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Client Id
        examples:
          Bauer Media:
            value: 5db1c6f588976c89fcb6bd70
          News UK Browser:
            value: 63247594f1861e200ef5b102
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyUsersRequest'
      responses:
        '200':
          description: User linked
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/user/create-users-with-roles:
    post:
      tags:
      - Users
      summary: Create Users With Roles
      description: 'Creates multiple Cognito users in bulk with specific roles and associated companies.


        Expects payload like:

        {

        "emails": ["imran+bulk1@covatic.com", "imran+bulk2@covatic.com"],

        "roles": ["super_admin"],

        "associated_companies": [

        {

        "parent_id": "BBC",

        "parent_type": "company",

        "is_default": true,

        "permissions": ["insights", "advertising"]

        }

        ],

        "company": {

        "parent_id": "BBC",

        "parent_type": "company"

        }

        }'
      operationId: create_users_with_roles_api_v1_user_create_users_with_roles_post
      security:
      - HTTPBearer: []
      parameters:
      - name: parent_type
        in: query
        required: true
        schema:
          type: string
          maxLength: 50
          title: Parent Type
        examples:
          Octave:
            value: company
          Bauer UK:
            value: sub-company
          News UK:
            value: sub-company
      - name: parent_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 50
          title: Parent Name
        examples:
          Octave:
            value: Octave
          Bauer UK:
            value: Bauer UK
          News UK:
            value: News UK
      - name: client_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Client Id
        examples:
          Bauer Media:
            value: 5db1c6f588976c89fcb6bd70
          News UK Browser:
            value: 63247594f1861e200ef5b102
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUsersWithRolesRequest'
      responses:
        '200':
          description: Users created with roles
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/user/resend-invite:
    post:
      tags:
      - Users
      summary: Resend Invite
      description: Resend invite to an existing Cognito user
      operationId: resend_invite_api_v1_user_resend_invite_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserEmailRequestModel'
        required: true
      responses:
        '200':
          description: User invite sent successfully
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/user/delete/{user_cognito_id}:
    delete:
      tags:
      - Users
      summary: Delete User
      description: 'Delete a user from Cognito, the database, and QuickSight.


        Process:

        1. Retrieve user record from DB (to obtain email and company for QS cleanup)

        2. Attempt to delete from Cognito

        3. If user deleted from Cognito OR user doesn''t exist in Cognito:

        - Proceed to delete from database

        4. Best-effort removal from QuickSight (revoke dashboard + delete QS user)

        5. If Cognito deletion fails with an error:

        - Do NOT delete from database to maintain data consistency

        - Raise HTTP 500 error


        Args:

        user_cognito_id: The Cognito user ID to delete


        Returns:

        Success response with deletion details


        Raises:

        HTTPException: If Cognito deletion fails due to error or user not found anywhere'
      operationId: delete_user_api_v1_user_delete__user_cognito_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_cognito_id
        in: path
        required: true
        schema:
          type: string
          title: User Cognito Id
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models__profile__Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/user/update:
    put:
      tags:
      - Users
      summary: Update User
      description: 'Update user''s associated companies and roles.


        Expects payload like:

        {

        "user_cognito_id": "3314b812-d061-7062-b980-5acc06868d34",

        "associated_companies": [

        {

        "parent_id": "Covatic US",

        "parent_type": "company",

        "is_default": false,

        "permissions": ["insights", "advertising"]

        },

        {

        "parent_id": "Covatic",

        "parent_type": "company",

        "is_default": true,

        "permissions": ["insights", "advertising"]

        }

        ],

        "roles": ["admin"]

        }'
      operationId: update_user_api_v1_user_update_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequestModel'
        required: true
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models__profile__Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    SubCompany:
      properties:
        sub_company_name:
          type: string
          title: Sub Company Name
        clients:
          items:
            $ref: '#/components/schemas/Client'
          type: array
          title: Clients
        sub_company_permissions:
          items:
            type: string
          type: array
          title: Sub Company Permissions
      type: object
      required:
      - sub_company_name
      - clients
      - sub_company_permissions
      title: SubCompany
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Page_Company_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Company'
          type: array
          title: Items
        total:
          type: integer
          minimum: 0.0
          title: Total
        page:
          type: integer
          minimum: 1.0
          title: Page
        size:
          type: integer
          minimum: 1.0
          title: Size
        pages:
          type: integer
          minimum: 0.0
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - size
      - pages
      title: Page[Company]
    Client:
      properties:
        client_id:
          type: string
          title: Client Id
          example: 5eb7cf5a86d9755df3a6c593
        client_name:
          type: string
          title: Client Name
        platform:
          type: string
          title: Platform
        location:
          anyOf:
          - type: string
          - type: 'null'
          title: Location
        country:
          type: string
          title: Country
        sec_type:
          type: string
          title: Sec Type
        bucket_name:
          type: string
          title: Bucket Name
        code_name:
          type: string
          title: Code Name
        cluster_reference:
          type: string
          title: Cluster Reference
        restricted_access:
          type: boolean
          title: Restricted Access
      type: object
      required:
      - client_id
      - client_name
      - platform
      - country
      - sec_type
      - bucket_name
      - code_name
      - cluster_reference
      - restricted_access
      title: Client
    UpdateUserRequestModel:
      properties:
        user_cognito_id:
          type: string
          title: User Cognito Id
        associated_companies:
          items:
            $ref: '#/components/schemas/CompanyAccess'
          type: array
          title: Associated Companies
        roles:
          items:
            type: string
          type: array
          title: Roles
      type: object
      required:
      - user_cognito_id
      - associated_companies
      - roles
      title: UpdateUserRequestModel
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Page_Any_:
      properties:
        items:
          items: {}
          type: array
          title: Items
        total:
          type: integer
          minimum: 0.0
          title: Total
        page:
          type: integer
          minimum: 1.0
          title: Page
        size:
          type: integer
          minimum: 1.0
          title: Size
        pages:
          type: integer
          minimum: 0.0
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - size
      - pages
      title: Page[Any]
    CompanyAccess:
      properties:
        parent_type:
          type: string
          title: Parent Type
        parent_id:
          type: string
          title: Parent Id
        is_default:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Default
          default: false
        permissions:
          items:
            type: string
          type: array
          title: Permissions
      type: object
      required:
      - parent_type
      - parent_id
      - permissions
      title: CompanyAccess
    models__profile__Response:
      properties:
        status_code:
          type: integer
          title: Status Code
        response_type:
          type: string
          title: Response Type
        description:
          type: string
          title: Description
        data:
          anyOf:
          - {}
          - type: 'null'
          title: Data
      type: object
      required:
      - status_code
      - response_type
      - description
      - data
      title: Response
      example:
        data: []
        description: Operation successful
        response_type: success
        status_code: 200
    CompanyRequest:
      properties:
        parent_id:
          type: string
          title: Parent Id
        parent_type:
          type: string
          title: Parent Type
      type: object
      required:
      - parent_id
      - parent_type
      title: CompanyRequest
    AudienceCodeFormat:
      type: string
      enum:
      - numeric_6
      - alphanumeric_3
      title: AudienceCodeFormat
      description: Audience code format enumeration
    UserEmailRequestModel:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: UserEmailRequestModel
    Company:
      properties:
        _id:
          anyOf:
          - type: string
            example: 5eb7cf5a86d9755df3a6c593
          - type: 'null'
          title: Id
          description: MongoDB document ObjectID
        revision_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Revision Id
          hidden: true
        company_name:
          type: string
          minLength: 1
          title: Company Name
          description: Company name must not be empty.
        company_permissions:
          items:
            type: string
          type: array
          title: Company Permissions
        qs_dashboard:
          additionalProperties:
            type: string
          type: object
          title: Qs Dashboard
          default: {}
        sub_companies:
          items:
            $ref: '#/components/schemas/SubCompany'
          type: array
          title: Sub Companies
        audience_code_format:
          anyOf:
          - $ref: '#/components/schemas/AudienceCodeFormat'
          - type: 'null'
          description: Format for generating audience codes. Defaults to 6-digit numeric.
          default: numeric_6
      type: object
      required:
      - company_name
      - company_permissions
      - sub_companies
      title: Company
      example:
        audience_code_format: numeric_6
        company_name: Octave
        company_permissions:
        - insights
        - advertising
        sub_companies:
        - clients:
          - client_id: '123'
            client_name: Bauer UK Client 1
            country: UK
            platform: Web
          sub_company_name: Bauer UK
          sub_company_permissions:
          - insights
          - notifications
        - clients:
          - client_id: '789'
            client_name: News UK Client 1
          sub_company_name: News UK
          sub_company_permissions:
          - insights
          - notifications
    CreateUsersWithRolesRequest:
      properties:
        emails:
          items:
            type: string
            format: email
          type: array
          title: Emails
        roles:
          items:
            type: string
          type: array
          title: Roles
        associated_companies:
          items:
            $ref: '#/components/schemas/CompanyAccess'
          type: array
          title: Associated Companies
        company:
          $ref: '#/components/schemas/CompanyCreateUsersRequest'
      type: object
      required:
      - emails
      - roles
      - associated_companies
      - company
      title: CreateUsersWithRolesRequest
    CreateCompanyUsersRequest:
      properties:
        emails:
          items:
            type: string
            format: email
          type: array
          title: Emails
        company:
          $ref: '#/components/schemas/CompanyCreateUsersRequest'
      type: object
      required:
      - emails
      - company
      title: CreateCompanyUsersRequest
    CompanyCreateUsersRequest:
      properties:
        parent_id:
          type: string
          title: Parent Id
        parent_type:
          type: string
          title: Parent Type
      type: object
      required:
      - parent_id
      - parent_type
      title: CompanyCreateUsersRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer