OpenAPI Specification
openapi: 3.0.3
info:
title: Coalesce Environments Users API
description: REST API for integrating with Coalesce, a unified data transformation platform built for Snowflake. Enables automation of pipeline runs, querying metadata about nodes and environments, user management, git account configuration, project management, and CI/CD integration for data warehouse transformation pipelines.
version: '1'
contact:
name: Coalesce Support
email: support@coalesce.io
url: https://docs.coalesce.io/docs/api
x-api-id: coalesce-api
x-audience: public
servers:
- url: https://app.coalescesoftware.io/api/v1
description: US (default)
- url: https://app.us-east-1.aws.coalescesoftware.io/api/v1
description: US East (AWS)
- url: https://app.eu.coalescesoftware.io/api/v1
description: Europe
- url: https://app.northamerica-northeast1.gcp.coalescesoftware.io/api/v1
description: Canada (GCP)
- url: https://app.australia-southeast1.gcp.coalescesoftware.io/api/v1
description: Australia (GCP)
security:
- bearerAuth: []
tags:
- name: Users
description: Manage organization users and roles
paths:
/users:
get:
operationId: listUsers
summary: List Organization Users
description: Returns a paginated list of users in the organization.
tags:
- Users
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/orderByParam'
- $ref: '#/components/parameters/orderByDirectionParam'
- $ref: '#/components/parameters/startingFromParam'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{userID}/roles/org:
parameters:
- name: userID
in: path
required: true
description: Unique identifier of the user
schema:
type: string
put:
operationId: setUserOrgRole
summary: Set User Organization Role
description: Assigns or updates a user's organization-level role.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RoleInput'
responses:
'200':
description: Role updated
content:
application/json:
schema:
$ref: '#/components/schemas/UserRole'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteUserOrgRole
summary: Delete User Organization Role
description: Removes a user's organization-level role.
tags:
- Users
responses:
'204':
description: Role removed
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{userID}/roles/project/{projectID}:
parameters:
- name: userID
in: path
required: true
description: Unique identifier of the user
schema:
type: string
- name: projectID
in: path
required: true
description: Unique identifier of the project
schema:
type: string
put:
operationId: setUserProjectRole
summary: Set User Project Role
description: Assigns or updates a user's project-level role.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RoleInput'
responses:
'200':
description: Role updated
content:
application/json:
schema:
$ref: '#/components/schemas/UserRole'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteUserProjectRole
summary: Delete User Project Role
description: Removes a user's project-level role.
tags:
- Users
responses:
'204':
description: Role removed
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{userID}/roles/environment/{environmentID}:
parameters:
- name: userID
in: path
required: true
description: Unique identifier of the user
schema:
type: string
- name: environmentID
in: path
required: true
description: Unique identifier of the environment
schema:
type: string
put:
operationId: setUserEnvironmentRole
summary: Set User Environment Role
description: Assigns or updates a user's environment-level role.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RoleInput'
responses:
'200':
description: Role updated
content:
application/json:
schema:
$ref: '#/components/schemas/UserRole'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteUserEnvironmentRole
summary: Delete User Environment Role
description: Removes a user's environment-level role.
tags:
- Users
responses:
'204':
description: Role removed
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
parameters:
startingFromParam:
name: startingFrom
in: query
description: Cursor value from the previous response's `next` field for pagination
required: false
schema:
type: string
orderByDirectionParam:
name: orderByDirection
in: query
description: Sort direction
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
limitParam:
name: limit
in: query
description: Maximum number of results to return per page
required: false
schema:
type: integer
orderByParam:
name: orderBy
in: query
description: Field name to sort results by
required: false
schema:
type: string
schemas:
User:
type: object
properties:
id:
type: string
description: Unique user identifier
email:
type: string
format: email
description: User's email address
name:
type: string
description: User's display name
orgRole:
type: string
description: Organization-level role
UserRole:
type: object
properties:
userID:
type: string
description: User identifier
role:
type: string
description: Assigned role name
scope:
type: string
description: Role scope (org, project, environment)
PaginatedResponse:
type: object
properties:
data:
type: array
items: {}
next:
type: string
nullable: true
description: Cursor for the next page of results; null when exhausted
Error:
type: object
properties:
error:
type: string
description: Error message
code:
type: string
description: Error code
RoleInput:
type: object
required:
- role
properties:
role:
type: string
description: Role name to assign
UserList:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized - invalid or missing bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token obtained from the Deploy tab in the Coalesce application. Tokens never expire and remain valid across all environments and projects.