openapi: 3.0.3 info: title: Elemo API version: 0.1.0 description: | # Introduction The Elemo API allows you to manage users, organizations and other resources within Elemo in a programmatic way. The API is capable of doing all operations that can be executed from the user interface. You may use any tool that handles HTTP requests to interact with the API. However, the requests should be made using the HTTPS protocol so that traffic is encrypted. You need to obtain an [Access Token](https://en.wikipedia.org/wiki/Access_token) to call most of the API endpoints. The tokens are bound to users, therefore you must have a user in the system as well. Read more about obtaining an access token below. ## Requests The endpoints have support for the HTTP methods below. Please note that not all endpoints are supporting every HTTP method. | Method | Usage | |----------|------------------------------------------------------------------------------------------------------------------------------| | `GET` | Used to retrieve information about one or many resources. | | `POST` | Creates a new resource. The request must include all required attributes. | | `PUT` | Updates an existing resource. The request must include all required attributes. | | `PATCH` | Partially updates an existing resource. The request attributes are not required. Most of the resources are supporting PATCH. | | `DELETE` | Delete a resource from the system. Usually, this is an irreversible action. | ## Authentication Authentication is implemented based on the [OAuth 2.0](https://oauth.net/2/) specification supporting the password and authorization code flows. As a rule of thumb, whenever you need to interact with the API use authorization code flow and fallback to password flow if other flows cannot be implemented for any reason. After the token obtained, use the token as part of the `Authorization` HTTP header in the format of: `Authorization: Bearer {access_token}` ## Pagination All endpoints that are returning a list of resources supports and requires pagination. The default page size is `100` items, controlled by the `limit` query parameter. To utilize pagination, you may define `offset` in addition which skips the defined results. Therefore, if `offset` is set to `100`, the endpoint will return the next page's results. Sample request: ```shell $ curl -H "Authorization: Bearer {access_token}" https://{domain}/api/v1/users?limit=100&offset=100 ``` Although the pagination is very flexible, it defines some constraints: * The maximum `limit` cannot be greater than `1000` * The minimum `limit` cannot be less than `1` * The minimum `offset` cannot be less than `0` ## Versioning ### APIs The endpoints are versioned and the version number is part of the path. When the required input or returned output of an endpoint is changed, the current version is being deprecated and a new version of the endpoint is created. Deprecated endpoints are removed when a new major application version is released. ### This specification In contrast with the APIs, this specification follows semantic versioning. tags: - name: System description: System resources. - name: Todo description: User todo items. - name: Organization description: Organizations in the system. - name: Namespace description: Namespaces in organizations. - name: Project description: Projects in namespaces. - name: User description: Users in the system. - name: Notification description: In-app notifications of the user. - name: Permission description: Permissions in the system. servers: - url: "https://{domain}/api" description: Self-hosted instance. variables: domain: description: domain default: example.com components: schemas: User: title: User type: object description: A user in the system. x-examples: example: id: 9bsv0s46s6s002p9ltq0 username: test-user first_name: Test last_name: User email: test.user@example.com picture: "https://example.com/users/my-user.png" title: Senior Software Engineer bio: I'm working smart on software. address: Remote phone: "+15555551234" links: - "https://example.com/my-user" languages: - en - hu status: id: active created_at: "2023-01-01T00:00:00Z" updated_at: null properties: id: type: string description: Unique identifier of the user. example: 9bsv0s46s6s002p9ltq0 username: type: string description: The unique username of the user. pattern: "^[a-z0-9-_]{3,50}$" minLength: 3 maxLength: 50 example: test-user first_name: type: string description: First name of the user. minLength: 1 maxLength: 50 example: Test last_name: type: string description: Last name of the user. example: User minLength: 1 maxLength: 50 email: type: string format: email example: user@example.com minLength: 6 maxLength: 254 description: Email address of the user. picture: type: string description: Profile picture of the user. format: uri example: "https://example.com/users/my-user.png" maxLength: 2000 nullable: true title: type: string description: Work title of the user. example: Senior Software Engineer minLength: 3 maxLength: 50 nullable: true bio: type: string description: Self description of the user. maxLength: 500 example: I'm working smart on software. nullable: true address: type: string minLength: 3 maxLength: 500 example: Remote description: Working address of the user. nullable: true phone: type: string example: "+15555551234" minLength: 7 maxLength: 16 description: Phone number of the user. nullable: true links: type: array description: Links to show on profile page. uniqueItems: true nullable: true items: type: string format: uri example: "https://example.com/my-user" maxLength: 2000 languages: type: array description: Languages of the user. uniqueItems: true items: $ref: "#/components/schemas/Language" status: $ref: "#/components/schemas/UserStatus" created_at: type: string format: date-time description: Date when the user was created. updated_at: type: string format: date-time description: Date when the user was updated. nullable: true required: - id - username - first_name - last_name - email - picture - title - bio - address - phone - links - languages - status - created_at - updated_at UserStatus: type: string enum: - active - pending - inactive - deleted example: active description: Status of the user. title: UserStatus OrganizationMember: title: OrganizationMember type: object description: A member of an organization with limited information. properties: id: type: string description: Unique identifier of the user. example: 9bsv0s46s6s002p9ltq0 first_name: type: string description: First name of the user. minLength: 1 maxLength: 50 example: Test last_name: type: string description: Last name of the user. example: User minLength: 1 maxLength: 50 email: type: string format: email example: user@example.com minLength: 6 maxLength: 254 description: Email address of the user. picture: type: string description: Profile picture of the user. format: uri example: "https://example.com/users/my-user.png" maxLength: 2000 nullable: true status: $ref: "#/components/schemas/UserStatus" roles: type: array description: Organization roles the user belongs to (includes virtual roles based on permissions). uniqueItems: true items: type: string example: - owner - admin required: - id - first_name - last_name - email - picture - status - roles Organization: title: Organization type: object description: An organization in the system. properties: id: type: string description: Unique identifier of the organization. example: 9bsv0s46s6s002p9ltq0 name: type: string description: Name of the organization. maxLength: 120 example: ACME Inc. minLength: 1 email: type: string format: email example: info@example.com minLength: 6 maxLength: 254 description: Email address of the organization. logo: type: string description: Logo of the organization. format: uri example: "https://example.com/static/logo.png" maxLength: 2000 nullable: true website: type: string description: Work title of the user. format: uri example: "https://example.com" maxLength: 2000 nullable: true status: $ref: "#/components/schemas/OrganizationStatus" members: type: array description: IDs of the users in the organization. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 teams: type: array description: IDs of the teams in the organization. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 namespaces: type: array description: IDs of the namespaces in the organization. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 created_at: type: string format: date-time description: Date when the organization was created. updated_at: type: string format: date-time description: Date when the organization was updated. nullable: true required: - id - name - email - logo - website - status - members - teams - namespaces - created_at - updated_at OrganizationStatus: type: string enum: - active - deleted example: active description: Status of the organization. title: OrganizationStatus ProjectStatus: type: string enum: - active - pending example: active description: Status of the project. title: ProjectStatus Namespace: title: Namespace type: object description: A namespace in an organization. x-examples: example: id: 9bsv0s46s6s002p9ltq0 name: Engineering description: Engineering team namespace projects: - id: 9bsv0s46s6s002p9ltq0 key: ENG name: Engineering Project description: Main engineering project logo: "https://example.com/logo.png" status: active documents: - id: 9bsv0s46s6s002p9ltq0 name: Project Plan excerpt: Overview of the project plan created_by: 9bsv0s46s6s002p9ltq0 created_at: "2023-01-01T00:00:00Z" created_at: "2023-01-01T00:00:00Z" updated_at: null properties: id: type: string description: Unique identifier of the namespace. example: 9bsv0s46s6s002p9ltq0 name: type: string description: Name of the namespace. maxLength: 120 example: Engineering minLength: 3 description: type: string description: Description of the namespace. maxLength: 500 example: Engineering team namespace minLength: 5 nullable: true projects: type: array description: Projects in the namespace. uniqueItems: true items: $ref: "#/components/schemas/PartialProject" documents: type: array description: Documents in the namespace. uniqueItems: true items: $ref: "#/components/schemas/PartialDocument" created_at: type: string format: date-time description: Date when the namespace was created. updated_at: type: string format: date-time description: Date when the namespace was updated. nullable: true required: - id - name - projects - documents - created_at - updated_at PartialProject: title: PartialProject type: object description: A simplified project that can be used in lists. x-examples: example: id: 9bsv0s46s6s002p9ltq0 key: ENG name: Engineering Project description: Main engineering project logo: "https://example.com/logo.png" status: active properties: id: type: string description: Unique identifier of the project. example: 9bsv0s46s6s002p9ltq0 key: type: string description: Key of the project. minLength: 3 maxLength: 6 example: ENG name: type: string description: Name of the project. minLength: 3 maxLength: 120 example: Engineering Project description: type: string description: Description of the project. maxLength: 500 example: Main engineering project minLength: 10 nullable: true logo: type: string description: Logo of the project. format: uri example: "https://example.com/logo.png" maxLength: 2000 nullable: true status: $ref: "#/components/schemas/ProjectStatus" required: - id - key - name - status Project: title: Project type: object description: A project in a namespace. x-examples: example: id: 9bsv0s46s6s002p9ltq0 key: ENG name: Engineering Project description: Main engineering project logo: "https://example.com/logo.png" status: active teams: - 9bsv0s46s6s002p9ltq0 documents: - id: 9bsv0s46s6s002p9ltq0 name: Project Plan excerpt: Overview of the project plan created_by: 9bsv0s46s6s002p9ltq0 created_at: "2023-01-01T00:00:00Z" issues: - 9bsv0s46s6s002p9ltq0 created_at: "2023-01-01T00:00:00Z" updated_at: null properties: id: type: string description: Unique identifier of the project. example: 9bsv0s46s6s002p9ltq0 key: type: string description: Key of the project. minLength: 3 maxLength: 6 example: ENG name: type: string description: Name of the project. minLength: 3 maxLength: 120 example: Engineering Project description: type: string description: Description of the project. maxLength: 500 example: Main engineering project minLength: 10 nullable: true logo: type: string description: Logo of the project. format: uri example: "https://example.com/logo.png" maxLength: 2000 nullable: true status: $ref: "#/components/schemas/ProjectStatus" teams: type: array description: IDs of the teams in the project. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 documents: type: array description: Documents in the project. uniqueItems: true items: $ref: "#/components/schemas/PartialDocument" issues: type: array description: IDs of the issues in the project. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 created_at: type: string format: date-time description: Date when the project was created. updated_at: type: string format: date-time description: Date when the project was updated. nullable: true required: - id - key - name - status - teams - documents - issues - created_at - updated_at PartialDocument: title: PartialDocument type: object description: A simplified document that can be used in listings. x-examples: example: id: 9bsv0s46s6s002p9ltq0 name: Project Plan excerpt: Overview of the project plan created_by: 9bsv0s46s6s002p9ltq0 created_at: "2023-01-01T00:00:00Z" properties: id: type: string description: Unique identifier of the document. example: 9bsv0s46s6s002p9ltq0 name: type: string description: Name of the document. minLength: 3 maxLength: 120 example: Project Plan excerpt: type: string description: Excerpt of the document. maxLength: 500 example: Overview of the project plan minLength: 10 nullable: true created_by: type: string description: ID of the user who created the document. example: 9bsv0s46s6s002p9ltq0 created_at: type: string format: date-time description: Date when the document was created. nullable: true required: - id - name - created_by Todo: title: Todo type: object description: A todo item belonging to a user. x-examples: example: id: 9bsv0s46s6s002p9ltq0 title: Do something great description: I'll make the world a better place today. priority: normal completed: true owned_by: string created_by: string due_date: null created_at: "2019-08-24T14:15:22Z" updated_at: null properties: id: type: string description: Unique identifier of the todo. example: 9bsv0s46s6s002p9ltq0 title: type: string minLength: 3 maxLength: 250 example: Do something great description: Title of the todo item. description: type: string minLength: 10 maxLength: 500 example: I'll make the world a better place today. description: Description of the todo item. priority: $ref: "#/components/schemas/TodoPriority" completed: type: boolean default: true description: Status of the todo item. owned_by: type: string description: ID of the user who owns the todo item. created_by: type: string description: ID of the user who created the todo item. due_date: type: string format: date-time description: Completion due date of the todo item. nullable: true created_at: type: string format: date-time description: Date when the todo item was created. updated_at: type: string format: date-time description: Date when the todo item was updated. nullable: true required: - id - title - description - priority - completed - owned_by - created_by - due_date - created_at - updated_at TodoPriority: type: string enum: - normal - important - urgent - critical example: urgent minLength: 6 maxLength: 9 description: Priority of the todo item. Notification: title: Notification type: object description: An in-app notification sent to the user. x-examples: example: id: 9bsv0s46s6s002p9ltq0 title: Do something great description: Make the world a better place! recipient: 9bsv0s46s6s002p9ltq0 read: false created_at: "2019-08-24T14:15:22Z" updated_at: null properties: id: type: string description: Unique identifier of the in-app notification. example: 9bsv0s46s6s002p9ltq0 title: type: string minLength: 3 maxLength: 120 example: Do something great description: Title of the in-app notification. description: type: string minLength: 5 maxLength: 500 example: Make the world a better place! description: Description of the in-app notification. recipient: type: string description: ID of the user who got notified. read: type: boolean default: false description: Whether the notification was read by the user. created_at: type: string format: date-time description: Date when the todo item was created. updated_at: type: string format: date-time description: Date when the in-app notification was updated. nullable: true required: - id - title - description - recipient - read - created_at - updated_at SystemHealth: title: SystemHealth type: object properties: cache_database: type: string enum: - healthy - unhealthy - unknown minLength: 7 maxLength: 9 description: Health of the cache database. graph_database: type: string enum: - healthy - unhealthy - unknown minLength: 7 maxLength: 9 description: Health of the graph database. relational_database: type: string enum: - healthy - unhealthy - unknown minLength: 7 maxLength: 9 description: Health of the relational database. license: type: string enum: - healthy - unhealthy - unknown minLength: 7 maxLength: 9 description: Health of the license. message_queue: type: string enum: - healthy - unhealthy - unknown minLength: 7 maxLength: 9 description: Health of the message queue. required: - cache_database - graph_database - relational_database - license - message_queue x-examples: example: cache_database: healthy graph_database: healthy relational_database: healthy license: healthy message_queue: healthy SystemVersion: title: SystemVersion type: object properties: version: type: string description: Version of the application. pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' commit: type: string description: Commit hash of the build. pattern: "^[0-9a-f]{5,40}$" date: type: string format: date-time description: Build date and time of the application. go_version: type: string description: Go version used to build the application. pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' required: - version - commit - date - go_version SystemLicense: title: SystemLicense type: object properties: id: type: string description: Unique ID identifying the license. organization: type: string description: Name of the organization the license belongs to. email: type: string format: email example: info@example.com minLength: 6 maxLength: 254 description: Email address of the licensee. quotas: type: object description: Quotas available for the license. required: - documents - namespaces - organizations - projects - roles - users properties: documents: type: integer minimum: 1 description: Number of documents can exist in the system. namespaces: type: integer minimum: 1 description: Number of namespaces can exist in the system. organizations: type: integer minimum: 1 description: Number of organizations active can exist in the system. projects: type: integer minimum: 1 description: Number of projects can exist in the system. roles: type: integer minimum: 1 description: Number of roles can exist in the system. users: type: integer minimum: 1 description: Number of active or pending users can exist in the system. features: type: array uniqueItems: true description: Features enabled by the license. items: type: string enum: - components - custom_statuses - custom_fields - multiple_assignees - releases expires_at: type: string format: date-time description: Date and time when the license expires. required: - id - organization - email - quotas - features - expires_at HTTPError: title: HTTPError type: object properties: message: type: string description: Description of the error. required: - message description: HTTP error description. Language: type: string description: Two-letter ISO language code. minLength: 2 maxLength: 2 enum: - aa - ab - ae - af - ak - am - an - ar - as - av - ay - az - ba - be - bg - bh - bi - bm - bn - bo - br - bs - ca - ce - ch - co - cr - cs - cu - cv - cy - da - de - dv - dz - ee - el - en - eo - es - et - eu - fa - ff - fi - fj - fo - fr - fy - ga - gd - gl - gn - gu - gv - ha - he - hi - ho - hr - ht - hu - hy - hz - ia - id - ie - ig - ii - ik - io - is - it - iu - ja - jv - ka - kg - ki - kj - kk - kl - km - kn - ko - kr - ks - ku - kv - kw - ky - la - lb - lg - li - ln - lo - lt - lu - lv - mg - mh - mi - mk - ml - mn - mr - ms - mt - my - na - nb - nd - ne - ng - nl - nn - "no" - nr - nv - ny - oc - oj - om - or - os - pa - pi - pl - ps - pt - qu - rm - rn - ro - ru - rw - sa - sc - sd - se - sg - si - sk - sl - sm - sn - so - sq - sr - ss - st - su - sv - sw - ta - te - tg - th - ti - tk - tl - tn - to - tr - ts - tt - tw - ty - ug - uk - ur - uz - ve - vi - vo - wa - wo - xh - yi - yo - za - zh - zu Permission: title: Permission type: object description: A permission in the system. x-examples: example: id: 9bsv0s46s6s002p9ltq0 kind: "*" created_at: "2023-01-01T00:00:00Z" updated_at: null properties: id: type: string description: Unique identifier of the user. example: 9bsv0s46s6s002p9ltq0 kind: $ref: "#/components/schemas/PermissionKind" subject: type: string example: 9bsv0s46s6s002p9ltq0 target: type: string description: Resource ID. example: "9bsv0s46s6s002p9ltq0" target_type: type: string description: Resource type of the target resource. example: "Organization" created_at: type: string format: date-time description: Date when the user was created. updated_at: type: string format: date-time description: Date when the user was updated. nullable: true required: - id - kind - subject - target - target_type - created_at - updated_at PermissionKind: title: PermissionKind type: string description: Kind of a permission. enum: - "*" - create - write - read - delete Role: title: Role type: object description: A role in the system. x-examples: example: id: 9bsv0s46s6s002p9ltq0 name: Collaborators description: Users who can collaborate on the project. members: - 9bsv0s46s6s002p9ltq0 permissions: - 9bsv0s46s6s002p9ltq0 created_at: "2023-01-01T00:00:00Z" updated_at: null properties: id: type: string description: Unique identifier of the role. example: 9bsv0s46s6s002p9ltq0 name: type: string description: Name of the role. maxLength: 120 example: Collaborators minLength: 3 description: type: string description: Description of the role. maxLength: 500 example: Users who can collaborate on the project. minLength: 5 nullable: true members: type: array description: IDs of the users assigned to the role. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 permissions: type: array description: IDs of the permissions assigned to the role. uniqueItems: true items: type: string example: 9bsv0s46s6s002p9ltq0 created_at: type: string format: date-time description: Date when the organization was created. updated_at: type: string format: date-time description: Date when the organization was updated. nullable: true required: - id - name - members - permissions - created_at - updated_at ResourceType: title: ResourceType type: string enum: - Assignment - Attachment - Comment - Document - Issue - IssueRelation - Label - Namespace - Organization - Permission - Project - ResourceType - Role - Todo - User examples: {} securitySchemes: oauth2: type: oauth2 flows: password: tokenUrl: /oauth/token scopes: organization: Read and write access to organizations. organization.read: Read access to organizations. namespace: Read and write access to namespaces. namespace.read: Read access to namespaces. project: Read and write access to projects. project.read: Read access to projects. user: Read and write access to users. user.read: Read access to users. todo: Read and write access to todo items. todo.read: Read access to todo items. role: Read and write access to roles. role.read: Read access to roles. notification: Read and write access to in-app notifications. notification.read: Read access to in-app notifications. refreshUrl: /oauth/authorize clientCredentials: tokenUrl: /oauth/token refreshUrl: /oauth/authorize scopes: organization: Read and write access to organizations. organization.read: Read access to organizations. namespace: Read and write access to namespaces. namespace.read: Read access to namespaces. project: Read and write access to projects. project.read: Read access to projects. user: Read and write access to users. user.read: Read access to users. todo: Read and write access to todo items. todo.read: Read access to todo items. role: Read and write access to roles. role.read: Read access to roles. notification: Read and write access to in-app notifications. notification.read: Read access to in-app notifications. authorizationCode: authorizationUrl: /oauth/authorize tokenUrl: /oauth/token refreshUrl: /oauth/token scopes: organization: Read and write access to organizations. organization.read: Read access to organizations. namespace: Read and write access to namespaces. namespace.read: Read access to namespaces. project: Read and write access to projects. project.read: Read access to projects. user: Read and write access to users. user.read: Read access to users. todo: Read and write access to todo items. todo.read: Read access to todo items. role: Read and write access to roles. role.read: Read access to roles. notification: Read and write access to in-app notifications. notification.read: Read access to in-app notifications. responses: "201": description: Example response content: application/json: schema: type: object additionalProperties: false properties: id: type: string description: ID of the newly created resource. required: - id "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/HTTPError" examples: example: value: message: Invalid input given "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/HTTPError" examples: example: value: message: Unauthorized request "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/HTTPError" examples: example: value: message: The requested operation is forbidden "404": description: The requested resource not found content: application/json: schema: $ref: "#/components/schemas/HTTPError" examples: example: value: message: The requested resource not found "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/HTTPError" examples: example: value: message: Internal Server Error parameters: offset: name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: Number of resources to skip. limit: name: limit in: query required: false schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Number of resources to return. id: name: id in: path required: true schema: type: string example: 9bsv0s46s6s002p9ltq0 description: ID of the resource. resourceId: name: resourceId in: path required: true schema: type: string example: Todo:9bsv0s46s6s002p9ltq0 description: ID of the resource combined with its resource type. user_email: name: email in: query required: true schema: type: string format: email example: user@example.com description: Email address of the user. force: name: force in: query required: false schema: type: boolean description: Irreversibly delete the user. roles: name: roles in: query required: true schema: type: array items: type: string enum: - Owner - Admin - Support description: ID of a role. requestBodies: UserPatch: content: application/json: schema: type: object properties: username: type: string description: The unique username of the user. pattern: "^[a-z0-9-_]{3,50}$" minLength: 3 maxLength: 50 example: test-user first_name: type: string description: First name of the user. minLength: 1 maxLength: 50 example: Test last_name: type: string description: Last name of the user. example: User minLength: 1 maxLength: 50 email: type: string format: email example: user@example.com minLength: 6 maxLength: 254 description: Email address of the user. password: type: string format: password maxLength: 64 minLength: 8 example: super-secret description: Password of the user. Required together with the new_password field. new_password: type: string format: password maxLength: 64 minLength: 8 example: super-secret description: New password of the user. picture: type: string description: Profile picture of the user. format: uri example: "https://example.com/users/my-user.png" maxLength: 2000 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true title: type: string description: Work title of the user. example: Senior Software Engineer minLength: 3 maxLength: 50 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true bio: type: string description: Self description of the user. maxLength: 500 example: I'm working smart on software. nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true address: type: string minLength: 3 maxLength: 500 example: Remote description: Working address of the user. nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true phone: type: string example: "+15555551234" minLength: 7 maxLength: 16 description: Phone number of the user. nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true links: type: array description: Links to show on profile page. uniqueItems: true items: type: string format: uri example: "https://example.com/my-user" maxLength: 2000 languages: type: array description: Languages of the user. uniqueItems: true items: $ref: "#/components/schemas/Language" status: $ref: "#/components/schemas/UserStatus" examples: example: value: username: test-user first_name: Test last_name: User email: user@example.com picture: "https://example.com/users/my-user.png" title: Senior Software Engineer bio: I'm working smart on software. address: Remote phone: "+15555551234" links: - "https://example.com/my-user" languages: - aa status: active description: "" UserCreate: content: application/json: schema: type: object properties: username: type: string description: The unique username of the user. pattern: "^[a-z0-9-_]{3,50}$" minLength: 3 maxLength: 50 example: test-user first_name: type: string description: First name of the user. minLength: 1 maxLength: 50 example: Test last_name: type: string description: Last name of the user. example: User minLength: 1 maxLength: 50 email: type: string format: email example: user@example.com minLength: 6 maxLength: 254 description: Email address of the user. password: type: string minLength: 8 maxLength: 64 example: super-secret format: password description: Password of the user. picture: type: string description: Profile picture of the user. format: uri example: "https://example.com/users/my-user.png" maxLength: 2000 nullable: true title: type: string description: Work title of the user. example: Senior Software Engineer minLength: 3 maxLength: 50 nullable: true bio: type: string description: Self description of the user. maxLength: 500 example: I'm working smart on software. nullable: true address: type: string minLength: 3 maxLength: 500 example: Remote description: Working address of the user. nullable: true phone: type: string example: "+15555551234" minLength: 7 maxLength: 16 description: Phone number of the user. nullable: true links: type: array description: Links to show on profile page. uniqueItems: true nullable: true items: type: string format: uri example: "https://example.com/my-user" maxLength: 2000 languages: type: array description: Languages of the user. uniqueItems: true nullable: true items: $ref: "#/components/schemas/Language" required: - username - email - password - first_name - last_name UserPasswordReset: description: "Password reset request." content: application/json: schema: type: object properties: token: type: string example: tDCVsHnzeOj278GIT85xU0s_ description: Token to verify password: type: string format: password maxLength: 64 minLength: 8 example: super-secret description: Password of the user. required: - password - token OrganizationInvitationAccept: description: "Organization invitation acceptance request." content: application/json: schema: type: object properties: token: type: string example: tDCVsHnzeOj278GIT85xU0s_ description: Invitation token from the invitation email password: type: string format: password maxLength: 64 minLength: 8 description: Password for the account (required if user is pending) required: - token TodoCreate: content: application/json: schema: type: object properties: title: type: string minLength: 3 maxLength: 250 example: Do something great description: Title of the todo item. description: type: string minLength: 10 maxLength: 500 example: I'll make the world a better place today. description: Description of the todo item. nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true priority: $ref: "#/components/schemas/TodoPriority" owned_by: type: string description: ID of the user who owns the todo item. due_date: type: string format: date-time description: Completion due date of the todo item. nullable: true x-go-type: "Optional[*time.Time]" x-go-type-skip-optional-pointer: true required: - title - priority - owned_by TodoPatch: content: application/json: schema: type: object properties: title: type: string minLength: 3 maxLength: 250 example: Do something great description: Title of the todo item. description: type: string minLength: 10 maxLength: 500 example: I'll make the world a better place today. description: Description of the todo item. nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true priority: $ref: "#/components/schemas/TodoPriority" completed: type: boolean description: Completion status of the todo item. owned_by: type: string description: ID of the user who owns the todo item. due_date: type: string format: date-time description: Completion due date of the todo item. nullable: true x-go-type: "Optional[*time.Time]" x-go-type-skip-optional-pointer: true NotificationPatch: content: application/json: schema: type: object properties: read: type: boolean description: Whether the notification was read by the user. required: - read OrganizationCreate: content: application/json: schema: type: object properties: name: type: string description: Name of the organization. maxLength: 120 example: ACME Inc. minLength: 1 email: type: string format: email example: info@example.com minLength: 6 maxLength: 254 description: Email address of the organization. logo: type: string description: Logo of the organization. format: uri example: "https://example.com/static/logo.png" maxLength: 2000 website: type: string description: Work title of the user. format: uri example: "https://example.com" maxLength: 2000 required: - name - email OrganizationPatch: content: application/json: schema: type: object properties: name: type: string example: ACME Inc. minLength: 1 maxLength: 120 description: Name of the organization. email: type: string format: email example: info@example.com minLength: 6 maxLength: 254 description: Email address of the organization. logo: type: string description: Logo of the organization. format: uri example: "https://example.com/static/logo.png" maxLength: 2000 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true website: type: string description: Work title of the user. format: uri example: "https://example.com" maxLength: 2000 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true status: $ref: "#/components/schemas/OrganizationStatus" NamespaceCreate: content: application/json: schema: type: object properties: name: type: string description: Name of the namespace. maxLength: 120 example: Engineering minLength: 3 description: type: string description: Description of the namespace. maxLength: 500 example: Engineering team namespace minLength: 5 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true required: - name NamespacePatch: content: application/json: schema: type: object properties: name: type: string description: Name of the namespace. maxLength: 120 example: Engineering minLength: 3 description: type: string description: Description of the namespace. maxLength: 500 example: Engineering team namespace minLength: 5 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true ProjectCreate: content: application/json: schema: type: object properties: key: type: string description: Key of the project. minLength: 3 maxLength: 6 example: ENG name: type: string description: Name of the project. minLength: 3 maxLength: 120 example: Engineering Project description: type: string description: Description of the project. maxLength: 500 example: Main engineering project minLength: 10 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true logo: type: string description: Logo of the project. format: uri example: "https://example.com/logo.png" maxLength: 2000 nullable: true status: $ref: "#/components/schemas/ProjectStatus" required: - key - name ProjectPatch: content: application/json: schema: type: object properties: key: type: string description: Key of the project. minLength: 3 maxLength: 6 example: ENG name: type: string description: Name of the project. minLength: 3 maxLength: 120 example: Engineering Project description: type: string description: Description of the project. maxLength: 500 example: Main engineering project minLength: 10 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true logo: type: string description: Logo of the project. format: uri example: "https://example.com/logo.png" maxLength: 2000 nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true status: $ref: "#/components/schemas/ProjectStatus" PermissionCreate: content: application/json: schema: type: object properties: kind: $ref: "#/components/schemas/PermissionKind" subject: type: object example: "user:9bsv0s46s6s002p9ltq0" required: - resourceType - id properties: resourceType: $ref: "#/components/schemas/ResourceType" id: type: string example: 9bsv0s46s6s002p9ltq0 target: type: object example: "user:9bsv0s46s6s002p9ltq0" required: - resourceType - id properties: resourceType: $ref: "#/components/schemas/ResourceType" id: type: string example: 9bsv0s46s6s002p9ltq0 required: - kind - subject - target PermissionPatch: content: application/json: schema: type: object properties: kind: $ref: "#/components/schemas/PermissionKind" required: - kind RoleCreate: content: application/json: schema: type: object properties: name: type: string description: Name of the role. maxLength: 120 example: Contributors minLength: 3 description: type: string example: Users who can collaborate on the project. minLength: 5 maxLength: 500 description: Description of the role. required: - name RolePatch: content: application/json: schema: type: object properties: name: type: string maxLength: 120 minLength: 3 description: Name of the role. example: Contributors description: type: string minLength: 5 maxLength: 500 description: Description of the role. example: Users who can collaborate on the project. nullable: true x-go-type: "Optional[string]" x-go-type-skip-optional-pointer: true RolePermissionCreate: content: application/json: schema: type: object properties: target: type: string description: Resource ID string in the format "ResourceType:id" or "ResourceType:00000000000000000000" for system-level permissions. example: "Organization:9bsv0s46s6s002p9ltq0" kind: $ref: "#/components/schemas/PermissionKind" required: - target - kind paths: /v1/users: get: summary: Get all users tags: - User responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/User" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" operationId: v1UsersGet description: Returns the paginated list of users parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" security: - oauth2: - user.read post: summary: Create new user tags: - User operationId: v1UsersCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" requestBody: $ref: "#/components/requestBodies/UserCreate" description: Create a new user. security: - oauth2: - user "/v1/users/reset": get: summary: Initiate password reset tags: - User parameters: - $ref: "#/components/parameters/user_email" responses: "200": description: OK "400": $ref: "#/components/responses/400" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1UserRequestPasswordReset description: Initiate password reset flow. security: [] post: summary: Reset user password tags: - User requestBody: $ref: "#/components/requestBodies/UserPasswordReset" responses: "200": description: OK "204": description: New token generated "400": $ref: "#/components/responses/400" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1UserResetPassword description: Reset the user password. security: [] "/v1/users/{id}": parameters: - $ref: "#/components/parameters/id" get: summary: Get user tags: - User responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1UserGet description: Return the requested user by its ID. security: - oauth2: - user.read delete: summary: Delete the user with the given ID. tags: - User operationId: v1UserDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Delete a user by its ID. The user is not deleted irreversibly until the "force" parameter is set to true. parameters: - $ref: "#/components/parameters/force" security: - oauth2: - user patch: summary: Update user tags: - User operationId: v1UserUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the given user. requestBody: $ref: "#/components/requestBodies/UserPatch" security: - oauth2: - user /v1/todos: get: summary: Get todo item tags: - Todo responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Todo" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" - schema: type: boolean in: query name: completed description: Completion status of the items. operationId: v1TodosGet description: Returns all todo items belonging to the current user. security: - oauth2: - todo.read post: summary: Create todo item operationId: v1TodosCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" description: Create a new todo item. security: - oauth2: - todo requestBody: $ref: "#/components/requestBodies/TodoCreate" tags: - Todo "/v1/todos/{id}": parameters: - $ref: "#/components/parameters/id" get: summary: Get todo item tags: - Todo responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Todo" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1TodoGet description: Return a todo item based on the todo id belonging to the current user. security: - oauth2: - todo.read delete: summary: Delete todo item operationId: v1TodoDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" tags: - Todo description: Delete todo by its ID. security: - oauth2: - todo patch: summary: Update todo operationId: v1TodoUpdate requestBody: $ref: "#/components/requestBodies/TodoPatch" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Todo" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the given todo tags: - Todo security: - oauth2: - todo /v1/notifications: get: summary: Get all in-app notification of the requesting user. tags: - Notification responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Notification" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" operationId: v1NotificationsGet description: Returns the paginated list of in-app notifications parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" security: - oauth2: - notification.read "/v1/notifications/{id}": parameters: - $ref: "#/components/parameters/id" get: summary: Get an in-app notification tags: - Notification responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Notification" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1NotificationGet description: Return the requested notification by its ID. security: - oauth2: - notification.read patch: summary: Update an in-app notification tags: - Notification operationId: v1NotificationUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Notification" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the given user. requestBody: $ref: "#/components/requestBodies/NotificationPatch" security: - oauth2: - notification delete: summary: Delete the notification with the given ID. tags: - Notification operationId: v1NotificationDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Delete a notification by its ID. security: - oauth2: - notification /v1/organizations: get: summary: Get organizations tags: - Organization responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Organization" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" operationId: v1OrganizationsGet description: Returns the list of organizations in the system. security: - oauth2: - organization.read parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" post: summary: Create organization operationId: v1OrganizationsCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" description: Create a new organization. security: - oauth2: - organization tags: - Organization requestBody: $ref: "#/components/requestBodies/OrganizationCreate" "/v1/organizations/{id}": parameters: - $ref: "#/components/parameters/id" get: summary: Get organization tags: - Organization responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Organization" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1OrganizationGet security: - oauth2: - organization.read description: Returns the given organization by its ID. delete: summary: Delete organization operationId: v1OrganizationDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Delete the organization by its ID. security: - oauth2: - organization tags: - Organization parameters: - $ref: "#/components/parameters/force" patch: summary: Update organization operationId: v1OrganizationUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Organization" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the organization by its ID. security: - oauth2: - organization tags: - Organization requestBody: $ref: "#/components/requestBodies/OrganizationPatch" "/v1/organizations/{id}/members": parameters: - $ref: "#/components/parameters/id" get: summary: Get organization members tags: - Organization - User responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/OrganizationMember" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1OrganizationMembersGet security: - oauth2: - organization.read - user.read description: Return the users that are members of the organization. post: summary: Add organization member operationId: v1OrganizationMembersAdd responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Add an existing user to an organization. security: - oauth2: - organization tags: - Organization - User requestBody: content: application/json: schema: type: object properties: user_id: type: string description: ID of the user to add. example: 9bsv0s46s6s002p9ltq0 required: - user_id "/v1/organizations/{id}/members/invite": parameters: - $ref: "#/components/parameters/id" post: summary: Invite member to organization operationId: v1OrganizationMembersInvite responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Send an invitation email to a user to join the organization. If the user doesn't exist, a pending user will be created. security: - oauth2: - organization tags: - Organization - User requestBody: content: application/json: schema: type: object properties: email: type: string format: email description: Email address of the user to invite. example: user@example.com role_id: type: string description: Optional role ID to assign the user to when they accept the invitation. example: 9bsv0s46s6s002p9ltq0 required: - email "/v1/organizations/{id}/members/{user_id}": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: user_id in: path required: true description: ID of the user. delete: summary: Remove organization member operationId: v1OrganizationMemberRemove responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Removes a member from the organization security: - oauth2: - organization tags: - Organization - User "/v1/organizations/{id}/members/{user_id}/invite": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: user_id in: path required: true description: ID of the user. delete: summary: Revoke invitation operationId: v1OrganizationMemberInviteRevoke responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Revoke an invitation for a user to join the organization security: - oauth2: - organization tags: - Organization - User "/v1/organizations/{id}/members/accept": parameters: - $ref: "#/components/parameters/id" post: summary: Accept organization invitation operationId: v1OrganizationMembersAccept responses: "200": description: OK "204": description: Invitation accepted successfully "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Accept an invitation to join an organization using an invitation token. If the user is pending, they will be activated. security: [] tags: - Organization - User requestBody: $ref: "#/components/requestBodies/OrganizationInvitationAccept" "/v1/organizations/${id}/roles": parameters: - $ref: "#/components/parameters/id" get: summary: Get organization roles description: Return the roles that are assigned to the organization. operationId: v1OrganizationRolesGet tags: - Organization - Role security: - oauth2: - organization.read - role.read parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Role" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" post: summary: Create a new role in the organization operationId: v1OrganizationRolesCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Create a new role and assign it to the organization. security: - oauth2: - organization - role tags: - Organization - Role requestBody: $ref: "#/components/requestBodies/RoleCreate" "/v1/organizations/${id}/roles/{role_id}": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: role_id in: path required: true description: ID of the role. get: summary: Get organization role operationId: v1OrganizationRoleGet tags: - Organization - Role responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Role" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" security: - oauth2: - organization.read - role.read description: Returns the given organization by its ID. patch: summary: Update organization role operationId: v1OrganizationRoleUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Role" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the organization role by its ID. security: - oauth2: - organization - role tags: - Organization - Role requestBody: $ref: "#/components/requestBodies/RolePatch" delete: summary: Delete organization role operationId: v1OrganizationRoleDelete tags: - Organization - Role responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Deletes a role that is assigned to the organization. security: - oauth2: - organization - role "/v1/organizations/{id}/roles/{role_id}/members": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: role_id in: path required: true description: ID of the role. get: summary: Get organization role members tags: - Organization - Role - User responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/User" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1OrganizationRoleMembersGet security: - oauth2: - organization.read - role.read - user.read description: Return the users that are members of the organization's role. post: summary: Add organization role member operationId: v1OrganizationRoleMembersAdd responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Add an existing user to an organization's role. security: - oauth2: - organization - role tags: - Organization - Role - User requestBody: content: application/json: schema: type: object properties: user_id: type: string description: ID of the user to add. example: 9bsv0s46s6s002p9ltq0 required: - user_id "/v1/organizations/{id}/roles/{role_id}/members/{user_id}": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: role_id in: path required: true description: ID of the role. - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: user_id in: path required: true description: ID of the user. delete: summary: Remove organization role member operationId: v1OrganizationRoleMemberRemove responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Removes a member from the organization's role security: - oauth2: - organization - role tags: - Organization - Role - User "/v1/organizations/{id}/roles/{role_id}/permissions": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: role_id in: path required: true description: ID of the role. get: summary: Get organization role permissions operationId: v1OrganizationRolePermissionsGet tags: - Organization - Role - Permission responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Permission" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Return the permissions assigned to the organization's role. security: - oauth2: - organization.read - role.read - permission.read post: summary: Add permission to organization role operationId: v1OrganizationRolePermissionAdd tags: - Organization - Role - Permission responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Add a permission to an organization's role. Only organization-scoped resources (Organization, Namespace, Document, Project, Role) are allowed. security: - oauth2: - organization - role - permission requestBody: $ref: "#/components/requestBodies/RolePermissionCreate" "/v1/organizations/{id}/roles/{role_id}/permissions/{permission_id}": parameters: - $ref: "#/components/parameters/id" - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: role_id in: path required: true description: ID of the role. - schema: type: string example: 9bsv0s46s6s002p9ltq0 name: permission_id in: path required: true description: ID of the permission. delete: summary: Remove permission from organization role operationId: v1OrganizationRolePermissionRemove tags: - Organization - Role - Permission responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Removes a permission from the organization's role. security: - oauth2: - organization - role - permission "/v1/organizations/{id}/namespaces": parameters: - $ref: "#/components/parameters/id" get: summary: Get organization namespaces tags: - Organization - Namespace responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Namespace" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1OrganizationsNamespacesGet security: - oauth2: - organization.read - namespace.read description: Return the namespaces that belong to the organization. parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" post: summary: Create namespace in organization operationId: v1OrganizationsNamespacesCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Create a new namespace in the organization. security: - oauth2: - organization - namespace tags: - Organization - Namespace requestBody: $ref: "#/components/requestBodies/NamespaceCreate" "/v1/namespaces/{id}": parameters: - $ref: "#/components/parameters/id" get: summary: Get namespace tags: - Namespace responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Namespace" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1NamespaceGet security: - oauth2: - namespace.read description: Return the requested namespace by its ID. patch: summary: Update namespace operationId: v1NamespaceUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Namespace" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the namespace by its ID. security: - oauth2: - namespace tags: - Namespace requestBody: $ref: "#/components/requestBodies/NamespacePatch" delete: summary: Delete namespace operationId: v1NamespaceDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Delete the namespace by its ID. security: - oauth2: - namespace tags: - Namespace "/v1/namespaces/{id}/projects": parameters: - $ref: "#/components/parameters/id" get: summary: Get namespace projects tags: - Namespace - Project responses: "200": description: OK content: application/json: schema: type: array uniqueItems: true items: $ref: "#/components/schemas/Project" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1NamespacesProjectsGet security: - oauth2: - namespace.read - project.read description: Return the projects that belong to the namespace. parameters: - $ref: "#/components/parameters/offset" - $ref: "#/components/parameters/limit" post: summary: Create project in namespace operationId: v1NamespacesProjectsCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Create a new project in the namespace. security: - oauth2: - namespace - project tags: - Namespace - Project requestBody: $ref: "#/components/requestBodies/ProjectCreate" "/v1/projects/{id}": parameters: - $ref: "#/components/parameters/id" get: summary: Get project tags: - Project responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Project" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" operationId: v1ProjectGet security: - oauth2: - project.read description: Return the requested project by its ID. patch: summary: Update project operationId: v1ProjectUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Project" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update the project by its ID. security: - oauth2: - project tags: - Project requestBody: $ref: "#/components/requestBodies/ProjectPatch" delete: summary: Delete project operationId: v1ProjectDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Delete the project by its ID. security: - oauth2: - project tags: - Project /v1/permissions: post: summary: Create permission operationId: v1PermissionsCreate responses: "201": $ref: "#/components/responses/201" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" description: Create a new permission for a subject to the given target. security: - oauth2: [] tags: - Permission requestBody: $ref: "#/components/requestBodies/PermissionCreate" "/v1/permissions/{id}": parameters: - $ref: "#/components/parameters/id" patch: summary: Update permission operationId: v1PermissionUpdate responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Permission" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Update a permission. security: - oauth2: [] tags: - Permission requestBody: $ref: "#/components/requestBodies/PermissionPatch" delete: summary: Delete permission operationId: v1PermissionDelete responses: "204": description: No Content "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Delete a permission by its ID. security: - oauth2: [] tags: - Permission get: summary: Get permission operationId: v1PermissionGet responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Permission" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Get a permission by its ID. security: - oauth2: [] tags: - Permission "/v1/permissions/resources/{resourceId}": parameters: - $ref: "#/components/parameters/resourceId" get: summary: Get permissions for a resource operationId: v1PermissionResourceGet responses: "200": description: OK content: application/json: schema: type: array items: $ref: "#/components/schemas/Permission" "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "403": $ref: "#/components/responses/403" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Get all permissions the caller have for a given resource. security: - oauth2: [] tags: - Permission "/v1/permissions/has-relations/{resourceId}": parameters: - $ref: "#/components/parameters/resourceId" get: summary: Check relations to resource operationId: v1PermissionHasRelations responses: "200": description: OK content: application/json: schema: type: boolean "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "404": $ref: "#/components/responses/404" "500": $ref: "#/components/responses/500" description: Check if the caller has any relations to a given resource. security: - oauth2: [] tags: - Permission /v1/permissions/has-system-role: parameters: [] get: summary: Check system role assignment operationId: v1PermissionHasSystemRole responses: "200": description: OK content: application/json: schema: type: boolean "400": $ref: "#/components/responses/400" "401": $ref: "#/components/responses/401" "500": $ref: "#/components/responses/500" description: "Check if the user is member of one or more system roles." security: - oauth2: [] tags: - Permission parameters: - $ref: "#/components/parameters/roles" /v1/system/health: get: summary: Get system health responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SystemHealth" "500": $ref: "#/components/responses/500" operationId: v1SystemHealth description: Returns the health of registered components. security: [] tags: - System /v1/system/heartbeat: get: summary: Get heartbeat tags: - System responses: "200": description: OK content: text/plain: schema: type: string enum: - OK "500": $ref: "#/components/responses/500" operationId: v1SystemHeartbeat description: Returns 200 OK if the service is reachable. security: [] /v1/system/license: get: summary: Get license info tags: - System responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SystemLicense" "403": $ref: "#/components/responses/403" "500": $ref: "#/components/responses/500" operationId: v1SystemLicense description: Return the license information. The license information is only available to entitled users. security: - oauth2: [] /v1/system/version: get: summary: Get system version responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/SystemVersion" "500": $ref: "#/components/responses/500" operationId: v1SystemVersion description: Returns the version information of the system. security: [] tags: - System