{ "components": { "schemas": { "domain.Action": { "enum": [ "", "create", "read", "write", "manage", "assign", "close", "delete" ], "type": "string", "x-enum-varnames": [ "UnknownAction", "CreateAction", "ReadAction", "WriteAction", "ManageAction", "AssignAction", "CloseAction", "DeleteAction" ] }, "domain.Attachment": { "properties": { "composing": { "description": "Composing marks the attachment as belonging to an active message composition session.\nThe term mirrors the \"compose\" state in messaging clients: the user is writing a message but has not sent it yet.\nOnce the message is sent, ClaimAttachments links these attachments to it and clears this flag.\nComposing attachments are excluded from all list queries and are eligible for periodic cleanup if never claimed.", "type": "boolean" }, "contentId": { "description": "ContentID is the MIME Content-ID value used in cid: URI references within the message body.", "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "creator": { "$ref": "#/components/schemas/domain.Contact" }, "creatorId": { "type": "integer" }, "id": { "type": "integer" }, "inline": { "description": "Inline indicates that the attachment is meant to be displayed within the message content rather than as a separate downloadable file.", "type": "boolean" }, "link": { "description": "Link refers to the download URL for the attachment. Relative path for the API endpoint that requires authorization,\nnot a pre-signed URL or direct S3 link. This is generated on the fly and not stored in the DB.", "type": "string" }, "messageId": { "type": "integer" }, "name": { "type": "string" }, "size": { "type": "number" }, "threadId": { "description": "An attachment is listed under the thread or message it belongs to, so the two\nways back are redundant there and close both cycles in the schema. The ids\nidentify them; selecting the relations still works.", "type": "integer" } }, "type": "object" }, "domain.Channel": { "properties": { "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "id": { "type": "integer" }, "kind": { "$ref": "#/components/schemas/domain.ChannelKind" }, "name": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/domain.ChannelPurpose" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "tenantId": { "type": "integer" }, "updatedAt": { "type": "string" } }, "type": "object" }, "domain.ChannelIdentityDirection": { "enum": [ "", "INBOUND", "OUTBOUND" ], "type": "string", "x-enum-varnames": [ "ChannelIdentityDirectionUnknown", "ChannelIdentityDirectionInbound", "ChannelIdentityDirectionOutbound" ] }, "domain.ChannelKind": { "enum": [ "", "EMAIL", "WEBHOOK", "TEAMS", "SMS", "WHATSAPP", "WEBCHAT", "NOTICE" ], "type": "string", "x-enum-varnames": [ "ChannelKindUnknown", "ChannelKindEmail", "ChannelKindWebhook", "ChannelKindTeams", "ChannelKindSMS", "ChannelKindWhatsApp", "ChannelKindWebchat", "ChannelKindNotice" ] }, "domain.ChannelPurpose": { "enum": [ "", "THREAD", "TICKET", "NOTIFICATION" ], "type": "string", "x-enum-varnames": [ "ChannelPurposeUnknown", "ChannelPurposeThread", "ChannelPurposeTicket", "ChannelPurposeNotification" ] }, "domain.Contact": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "description": "AutoAssign / AssignmentContext drive automated ticket routing. Set today only on\nGROUP-kind contacts via the group endpoints; nil/empty on ordinary contacts.", "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "email": { "example": "ada.lovelace@example.com", "type": "string" }, "firstName": { "example": "Ada", "type": "string" }, "id": { "example": 17, "type": "integer" }, "kind": { "$ref": "#/components/schemas/domain.ContactKind" }, "lastName": { "example": "Lovelace", "type": "string" }, "mobile": { "type": "string" }, "phone": { "type": "string" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "tenantId": { "type": "integer" }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.ContactKind": { "enum": [ "", "PERSON", "INTAKE", "GROUP" ], "type": "string", "x-enum-varnames": [ "ContactKindUnknown", "ContactKindPerson", "ContactKindIntake", "ContactKindGroup" ] }, "domain.Event": { "properties": { "actorId": { "type": "integer" }, "actorSnapshot": { "description": "ActorSnapshot is the actor's display summary, frozen at emit. The actor id\n(ActorID) is kept for filtering/audit; ActorSnapshot is what reads render.", "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "aggregateChanges": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "aggregateId": { "type": "integer" }, "aggregateSnapshot": {}, "aggregateType": { "type": "string" }, "attempts": { "type": "integer" }, "eventType": { "$ref": "#/components/schemas/domain.EventType" }, "id": { "type": "integer" }, "lastError": { "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextAttemptAt": { "type": "string" }, "occurredAt": { "type": "string" }, "publishedAt": { "type": "string" }, "scopeId": { "type": "integer" }, "scopeType": { "type": "string" }, "status": { "$ref": "#/components/schemas/domain.EventStatus" }, "tenantId": { "type": "integer" } }, "type": "object" }, "domain.EventStatus": { "enum": [ "PENDING", "PUBLISHING", "PUBLISHED", "DEAD" ], "type": "string", "x-enum-varnames": [ "EventPending", "EventPublishing", "EventPublished", "EventDead" ] }, "domain.EventType": { "enum": [ "CREATED", "UPDATED", "DELETED" ], "type": "string", "x-enum-varnames": [ "Created", "Updated", "Deleted" ] }, "domain.Group": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "description": "AutoAssign / AssignmentContext / ContactID are read-through from the group's\nGROUP-kind Contact (like Email/Phone); they are not stored on the group table.", "type": "boolean" }, "contactId": { "type": "integer" }, "description": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "integer" }, "members": { "items": { "$ref": "#/components/schemas/domain.GroupMember" }, "type": "array", "uniqueItems": false }, "name": { "type": "string" }, "phone": { "type": "string" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "tenantId": { "type": "integer" } }, "type": "object" }, "domain.GroupMember": { "properties": { "contact": { "$ref": "#/components/schemas/domain.Contact" }, "contactId": { "type": "integer" }, "group": { "$ref": "#/components/schemas/domain.Group" }, "groupId": { "description": "The composite PK (groupId, contactId) is the by-id analogue for this join\ntable: both key columns are filter+sort (the codegen sort-minimum + what a\nby-key Query(And(Eq,Eq)).Get needs). role reproduces the old GroupMemberFilter.Role.", "type": "integer" }, "role": { "$ref": "#/components/schemas/domain.GroupMemberRole" } }, "type": "object" }, "domain.GroupMemberRole": { "enum": [ "", "MEMBER", "ADMIN", "OBSERVER" ], "type": "string", "x-enum-varnames": [ "GroupMemberRoleUnknown", "GroupMemberRoleMember", "GroupMemberRoleAdmin", "GroupMemberRoleObserver" ] }, "domain.Identity": { "properties": { "createdAt": { "type": "string" }, "groups": { "items": { "$ref": "#/components/schemas/domain.Group" }, "type": "array", "uniqueItems": false }, "id": { "description": "id is the only queryable field — Identity is an internal skeleton (a global,\ntenant-less credential table with no user-facing list); the generic Query is\nused only for by-id loads. Type/value lookups stay bespoke (they hash the value).", "type": "integer" }, "type": { "$ref": "#/components/schemas/domain.IdentityType" }, "value": { "type": "string" }, "verifiedAt": { "type": "string" } }, "type": "object" }, "domain.IdentityType": { "enum": [ "", "EMAIL", "PHONE", "TOKEN", "URL" ], "type": "string", "x-enum-varnames": [ "IdentityTypeUnknown", "IdentityTypeEmail", "IdentityTypePhone", "IdentityTypeToken", "IdentityTypeURL" ] }, "domain.Key": { "properties": { "actor": { "$ref": "#/components/schemas/domain.User" }, "actorId": { "type": "integer" }, "createdAt": { "type": "string" }, "creator": { "$ref": "#/components/schemas/domain.User" }, "creatorId": { "type": "integer" }, "expiresAt": { "type": "string" }, "id": { "type": "integer" }, "ident": { "type": "string" }, "label": { "type": "string" }, "revokedAt": { "type": "string" }, "scopes": { "items": { "$ref": "#/components/schemas/domain.KeyScope" }, "type": "array", "uniqueItems": false }, "usedAt": { "type": "string" } }, "type": "object" }, "domain.KeyScope": { "enum": [ "", "INHERIT" ], "type": "string", "x-enum-varnames": [ "KeyScopeUnknown", "KeyScopeInherit" ] }, "domain.Label": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "description": "AutoAssign / AssignmentContext gate AI label classification: a label is a candidate only\nwhen AutoAssign is on, and then AssignmentContext must be non-empty. Description stays\nhuman-facing — the model reads AssignmentContext.", "type": "boolean" }, "color": { "example": "#4a90d9", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "id": { "example": 12, "type": "integer" }, "name": { "example": "hardware", "type": "string" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "tenantId": { "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.Message": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/domain.Attachment" }, "type": "array", "uniqueItems": false }, "author": { "$ref": "#/components/schemas/domain.Contact" }, "authorId": { "type": "integer" }, "content": { "type": "string" }, "contentPreview": { "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "type": "string" }, "direction": { "$ref": "#/components/schemas/domain.MessageDirection" }, "id": { "type": "integer" }, "originChannel": { "$ref": "#/components/schemas/domain.Channel" }, "originChannelId": { "type": "integer" }, "replyTo": { "$ref": "#/components/schemas/domain.Message" }, "replyToId": { "type": "integer" }, "threadId": { "description": "A message is only ever listed under its thread, so the way back is redundant\nthere and closes the thread→message→thread cycle in the schema. threadId\nidentifies it; \"?fields=thread\" still works.", "type": "integer" }, "updatedAt": { "type": "string" } }, "type": "object" }, "domain.MessageDirection": { "enum": [ "INTERNAL", "INBOUND", "OUTBOUND" ], "type": "string", "x-enum-varnames": [ "MessageDirectionInternal", "MessageDirectionInbound", "MessageDirectionOutbound" ] }, "domain.Notification": { "properties": { "attempts": { "type": "integer" }, "channel": { "$ref": "#/components/schemas/domain.Channel" }, "channelId": { "type": "integer" }, "config": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "createdAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "direction": { "$ref": "#/components/schemas/domain.NotificationDirection" }, "event": { "$ref": "#/components/schemas/domain.Event" }, "eventId": { "type": "integer" }, "externalMessageId": { "type": "string" }, "id": { "type": "integer" }, "identity": { "$ref": "#/components/schemas/domain.Identity" }, "identityId": { "type": "integer" }, "lastError": { "type": "string" }, "nextAttemptAt": { "type": "string" }, "payload": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "status": { "$ref": "#/components/schemas/domain.NotificationStatus" }, "tenantId": { "type": "integer" } }, "type": "object" }, "domain.NotificationDirection": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "x-enum-varnames": [ "NotificationDirectionInbound", "NotificationDirectionOutbound" ] }, "domain.NotificationStatus": { "enum": [ "PENDING", "DELIVERING", "DELIVERED", "DEAD" ], "type": "string", "x-enum-varnames": [ "NotificationPending", "NotificationDelivering", "NotificationDelivered", "NotificationDead" ] }, "domain.Tenant": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "domain.TenantRole": { "enum": [ "", "ADMIN", "MEMBER" ], "type": "string", "x-enum-varnames": [ "TenantRoleUnknown", "TenantRoleAdmin", "TenantRoleMember" ] }, "domain.Thread": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/domain.Attachment" }, "type": "array", "uniqueItems": false }, "channel": { "$ref": "#/components/schemas/domain.Channel" }, "channelId": { "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "externalId": { "type": "string" }, "id": { "example": 8801, "type": "integer" }, "messages": { "items": { "$ref": "#/components/schemas/domain.Message" }, "type": "array", "uniqueItems": false }, "parent": { "$ref": "#/components/schemas/domain.Thread" }, "parentId": { "type": "integer" }, "participants": { "items": { "$ref": "#/components/schemas/domain.Contact" }, "type": "array", "uniqueItems": false }, "status": { "$ref": "#/components/schemas/domain.ThreadStatus" }, "subject": { "example": "Printer on the 2nd floor is not printing", "type": "string" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "tenantId": { "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.ThreadParticipant": { "properties": { "contact": { "$ref": "#/components/schemas/domain.Contact" }, "contactId": { "type": "integer" }, "role": { "$ref": "#/components/schemas/domain.ThreadParticipantRole" }, "thread": { "$ref": "#/components/schemas/domain.Thread" }, "threadId": { "description": "The composite PK (threadId, contactId) is the by-id analogue for this join\ntable: both key columns are filter+sort (the codegen sort-minimum + what a\nby-key Query(And(Eq,Eq)).Get needs). The old ThreadParticipantFilter had no\nrole axis, so role stays untagged.", "type": "integer" } }, "type": "object" }, "domain.ThreadParticipantRole": { "enum": [ "", "OWNER", "CONTRIBUTOR", "OBSERVER" ], "type": "string", "x-enum-varnames": [ "ThreadParticipantRoleUnknown", "ThreadParticipantRoleOwner", "ThreadParticipantRoleContributor", "ThreadParticipantRoleObserver" ] }, "domain.ThreadStatus": { "enum": [ "", "OPEN", "CLOSED" ], "type": "string", "x-enum-varnames": [ "ThreadStatusUnknown", "ThreadStatusOpen", "ThreadStatusClosed" ] }, "domain.Ticket": { "properties": { "agent": { "$ref": "#/components/schemas/domain.Contact" }, "agentId": { "example": 23, "type": "integer" }, "assignee": { "$ref": "#/components/schemas/domain.Contact" }, "assigneeId": { "example": 17, "type": "integer" }, "contact": { "$ref": "#/components/schemas/domain.Contact" }, "contactId": { "example": 91, "type": "integer" }, "createdAt": { "example": "2026-03-14T09:12:00Z", "format": "date-time", "type": "string" }, "id": { "example": 4211, "type": "integer" }, "impact": { "$ref": "#/components/schemas/domain.TicketImpact" }, "impactName": { "type": "string" }, "labels": { "items": { "$ref": "#/components/schemas/domain.Label" }, "type": "array", "uniqueItems": false }, "opener": { "$ref": "#/components/schemas/domain.Contact" }, "openerId": { "example": 91, "type": "integer" }, "priority": { "$ref": "#/components/schemas/domain.TicketPriority" }, "priorityName": { "type": "string" }, "status": { "$ref": "#/components/schemas/domain.TicketStatus" }, "statusName": { "type": "string" }, "subject": { "example": "Printer on the 2nd floor is not printing", "type": "string" }, "summary": { "example": "The network printer on the 2nd floor has stopped accepting jobs since Monday; a restart did not help.", "type": "string" }, "thread": { "$ref": "#/components/schemas/domain.Thread" }, "threadId": { "example": 8801, "type": "integer" }, "type": { "$ref": "#/components/schemas/domain.TicketType" }, "typeName": { "type": "string" }, "updatedAt": { "example": "2026-03-14T11:03:00Z", "format": "date-time", "type": "string" }, "urgency": { "$ref": "#/components/schemas/domain.TicketUrgency" }, "urgencyName": { "type": "string" } }, "type": "object" }, "domain.TicketImpact": { "properties": { "color": { "example": "#f5a623", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "displayName": { "example": "Abteilung", "type": "string" }, "level": { "example": 2, "type": "integer" }, "name": { "example": "department", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.TicketLinkType": { "enum": [ "", "SUBTASK_OF", "PARENT_OF", "BLOCKED_BY", "BLOCKS", "DUPLICATE_OF", "DUPLICATED_BY", "CAUSED_BY", "CAUSES", "RELATES_TO" ], "type": "string", "x-enum-varnames": [ "TicketLinkTypeUnknown", "TicketLinkTypeSubtaskOf", "TicketLinkTypeParentOf", "TicketLinkTypeBlockedBy", "TicketLinkTypeBlocks", "TicketLinkTypeDuplicateOf", "TicketLinkTypeDuplicatedBy", "TicketLinkTypeCausedBy", "TicketLinkTypeCauses", "TicketLinkTypeRelatesTo" ] }, "domain.TicketLinkView": { "properties": { "createdAt": { "type": "string" }, "creator": { "$ref": "#/components/schemas/domain.Contact" }, "relatedTicket": { "$ref": "#/components/schemas/domain.Ticket" }, "type": { "$ref": "#/components/schemas/domain.TicketLinkType" } }, "type": "object" }, "domain.TicketPriority": { "properties": { "color": { "example": "#d0021b", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "displayName": { "example": "Hoch", "type": "string" }, "level": { "example": 3, "type": "integer" }, "name": { "example": "high", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.TicketStatus": { "properties": { "allowedSourceStatuses": { "items": { "$ref": "#/components/schemas/domain.TicketStatus" }, "type": "array", "uniqueItems": false }, "allowedTargetStatuses": { "items": { "$ref": "#/components/schemas/domain.TicketStatus" }, "type": "array", "uniqueItems": false }, "color": { "example": "#f5a623", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "displayName": { "example": "In progress", "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "example": "in_progress", "type": "string" }, "position": { "example": 2, "type": "integer" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.TicketStatusTransition": { "properties": { "role": { "type": "string" }, "sourceStatus": { "$ref": "#/components/schemas/domain.TicketStatus" }, "targetStatus": { "$ref": "#/components/schemas/domain.TicketStatus" } }, "type": "object" }, "domain.TicketType": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "description": "AutoAssign / AssignmentContext gate AI ticket-type classification, mirroring DisplayName.\nRead-only today: ticket types are seeded and have no create/patch surface yet, so both\nstay at their defaults until that surface lands.", "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "displayName": { "example": "Incident", "type": "string" }, "name": { "example": "incident", "type": "string" }, "position": { "example": 1, "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.TicketUrgency": { "properties": { "color": { "example": "#d0021b", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "displayName": { "example": "Hoch", "type": "string" }, "level": { "example": 3, "type": "integer" }, "name": { "example": "high", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "domain.User": { "properties": { "contacts": { "items": { "$ref": "#/components/schemas/domain.Contact" }, "type": "array", "uniqueItems": false }, "id": { "description": "id is the only queryable field — User is an internal/identity entity with no\nuser-facing scoped list; its reads are by-id (Query) or bespoke (identity/contact).", "type": "integer" }, "realm": { "type": "string" }, "sub": { "type": "string" }, "tenant": { "$ref": "#/components/schemas/domain.Tenant" }, "tenantId": { "type": "integer" }, "tenantRole": { "$ref": "#/components/schemas/domain.TenantRole" }, "username": { "type": "string" } }, "type": "object" }, "domain.UserNotification": { "properties": { "createdAt": { "description": "Sortable: the feed's canonical order (matches the timestamp shown to the user).", "type": "string" }, "id": { "description": "userId is NOT exposed — it is the owner Scope (server-enforced).", "type": "integer" }, "notification": { "$ref": "#/components/schemas/domain.Notification" }, "notificationId": { "type": "integer" }, "readAt": { "type": "string" }, "userId": { "type": "integer" } }, "type": "object" }, "middleware.ErrorBody": { "properties": { "code": { "description": "Code is the stable, machine-readable reason. Clients match on this, not on the message.", "example": "NOT_FOUND", "type": "string" }, "details": { "description": "Details carries structured context where an error has any — a conflict names what it\ncollided with. Absent otherwise." }, "message": { "example": "ticket.get: ticket: not found", "type": "string" } }, "type": "object" }, "middleware.ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/middleware.ErrorBody" } }, "type": "object" }, "time.Duration": { "enum": [ -9223372036854775808, 9223372036854775807, 1, 1000, 1000000, 1000000000, 60000000000, 3600000000000 ], "type": "integer", "x-enum-varnames": [ "minDuration", "maxDuration", "Nanosecond", "Microsecond", "Millisecond", "Second", "Minute", "Hour" ] }, "usecase.Me": { "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "tenantId": { "type": "integer" }, "userId": { "type": "integer" }, "username": { "type": "string" } }, "type": "object" }, "v1.AddChannelIdentityRequest": { "properties": { "direction": { "$ref": "#/components/schemas/domain.ChannelIdentityDirection" }, "type": { "$ref": "#/components/schemas/domain.IdentityType" }, "value": { "type": "string" } }, "required": [ "direction", "type", "value" ], "type": "object" }, "v1.AddChannelIdentityResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Channel" } }, "type": "object" }, "v1.AddChannelRequest": { "properties": { "active": { "type": "boolean" }, "config": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "kind": { "$ref": "#/components/schemas/domain.ChannelKind" }, "name": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/domain.ChannelPurpose" } }, "required": [ "kind", "name", "purpose" ], "type": "object" }, "v1.AddChannelResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Channel" } }, "type": "object" }, "v1.AddContactRequest": { "properties": { "description": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "mobile": { "type": "string" }, "phone": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "v1.AddContactResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Contact" } }, "type": "object" }, "v1.AddGroupMembersRequest": { "properties": { "members": { "items": { "$ref": "#/components/schemas/v1.AddGroupMembersRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "members" ], "type": "object" }, "v1.AddGroupMembersRequestItem": { "properties": { "contactId": { "type": "integer" }, "role": { "$ref": "#/components/schemas/domain.GroupMemberRole" } }, "required": [ "contactId", "role" ], "type": "object" }, "v1.AddGroupMembersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/domain.GroupMember" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.AddGroupRequest": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "type": "boolean" }, "description": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "v1.AddGroupResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Group" } }, "type": "object" }, "v1.AddKeyRequest": { "properties": { "actorId": { "type": "integer" }, "label": { "type": "string" }, "ttl": { "$ref": "#/components/schemas/time.Duration" } }, "required": [ "actorId", "label" ], "type": "object" }, "v1.AddKeyResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Key" }, "secret": { "type": "string" } }, "type": "object" }, "v1.AddLabelsRequest": { "properties": { "labels": { "items": { "$ref": "#/components/schemas/v1.AddLabelsRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "labels" ], "type": "object" }, "v1.AddLabelsRequestItem": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "type": "boolean" }, "color": { "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "v1.AddLabelsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/domain.Label" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.AddThreadMessageRequest": { "properties": { "attachmentIds": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "content": { "type": "string" }, "replyToId": { "type": "integer" } }, "required": [ "content" ], "type": "object" }, "v1.AddThreadMessageResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Message" } }, "type": "object" }, "v1.AddThreadParticipantsRequest": { "properties": { "participants": { "items": { "$ref": "#/components/schemas/v1.AddThreadParticipantsRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "participants" ], "type": "object" }, "v1.AddThreadParticipantsRequestItem": { "properties": { "contactId": { "type": "integer" }, "role": { "$ref": "#/components/schemas/domain.ThreadParticipantRole" } }, "required": [ "contactId", "role" ], "type": "object" }, "v1.AddThreadParticipantsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/domain.ThreadParticipant" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.AddThreadRequest": { "properties": { "description": { "type": "string" }, "parentId": { "type": "integer" }, "subject": { "type": "string" } }, "required": [ "subject" ], "type": "object" }, "v1.AddThreadResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Thread" } }, "type": "object" }, "v1.AddTicketLinksRequest": { "properties": { "links": { "items": { "$ref": "#/components/schemas/v1.AddTicketLinksRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "links" ], "type": "object" }, "v1.AddTicketLinksRequestItem": { "properties": { "ticketId": { "type": "integer" }, "type": { "$ref": "#/components/schemas/domain.TicketLinkType" } }, "required": [ "ticketId", "type" ], "type": "object" }, "v1.AddTicketLinksResponse-domain_TicketLinkView": { "properties": { "data": { "items": { "$ref": "#/components/schemas/domain.TicketLinkView" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.AddTicketRequest": { "properties": { "agentId": { "type": "integer" }, "assigneeId": { "type": "integer" }, "contactId": { "type": "integer" }, "description": { "type": "string" }, "subject": { "type": "string" }, "threadId": { "type": "integer" }, "typeName": { "type": "string" } }, "required": [ "description" ], "type": "object" }, "v1.AddTicketResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Ticket" } }, "type": "object" }, "v1.AddTicketStatusRequest": { "properties": { "allowedSourceStatusNames": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "allowedTargetStatusNames": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "color": { "type": "string" }, "displayName": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "type": "string" }, "position": { "type": "integer" } }, "required": [ "displayName", "name" ], "type": "object" }, "v1.AddTicketStatusResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.TicketStatus" } }, "type": "object" }, "v1.AddTicketStatusTransitionRequest": { "properties": { "role": { "type": "string" }, "sourceStatusName": { "type": "string" }, "targetStatusName": { "type": "string" } }, "required": [ "sourceStatusName", "targetStatusName" ], "type": "object" }, "v1.AddTicketStatusTransitionResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.TicketStatusTransition" } }, "type": "object" }, "v1.CheckPermissionsRequest": { "properties": { "requests": { "items": { "$ref": "#/components/schemas/v1.CheckPermissionsRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "requests" ], "type": "object" }, "v1.CheckPermissionsRequestItem": { "properties": { "action": { "$ref": "#/components/schemas/domain.Action" }, "domain": { "type": "string" }, "resource": { "type": "string" } }, "required": [ "action", "domain", "resource" ], "type": "object" }, "v1.CheckPermissionsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/v1.CheckPermissionsResponseItem" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.CheckPermissionsResponseItem": { "properties": { "action": { "$ref": "#/components/schemas/domain.Action" }, "allowed": { "type": "boolean" }, "domain": { "type": "string" }, "resource": { "type": "string" } }, "type": "object" }, "v1.DeleteChannelIdentityResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Channel" } }, "type": "object" }, "v1.DeleteTicketStatusRequest": { "properties": { "migrationTargetName": { "type": "string" } }, "type": "object" }, "v1.DeleteTicketStatusTransitionRequest": { "properties": { "sourceStatusName": { "type": "string" }, "targetStatusName": { "type": "string" } }, "required": [ "sourceStatusName", "targetStatusName" ], "type": "object" }, "v1.GetChannelResponse-domain_Channel": { "properties": { "data": { "$ref": "#/components/schemas/domain.Channel" } }, "type": "object" }, "v1.GetContactResponse-domain_Contact": { "properties": { "data": { "$ref": "#/components/schemas/domain.Contact" } }, "type": "object" }, "v1.GetGroupResponse-domain_Group": { "properties": { "data": { "$ref": "#/components/schemas/domain.Group" } }, "type": "object" }, "v1.GetLabelResponse-domain_Label": { "properties": { "data": { "$ref": "#/components/schemas/domain.Label" } }, "type": "object" }, "v1.GetMeResponse": { "properties": { "data": { "$ref": "#/components/schemas/usecase.Me" } }, "type": "object" }, "v1.GetNotificationResponse-domain_Notification": { "properties": { "data": { "$ref": "#/components/schemas/domain.Notification" } }, "type": "object" }, "v1.GetThreadResponse-domain_Thread": { "properties": { "data": { "$ref": "#/components/schemas/domain.Thread" } }, "type": "object" }, "v1.GetTicketResponse-domain_Ticket": { "properties": { "data": { "$ref": "#/components/schemas/domain.Ticket" } }, "type": "object" }, "v1.ListAttachmentsResponse-domain_Attachment": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Attachment" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListChannelsResponse-domain_Channel": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Channel" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListContactsResponse-domain_Contact": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Contact" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListGroupMembersResponse-domain_GroupMember": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.GroupMember" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListGroupsResponse-domain_Group": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Group" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListKeysResponse-domain_Key": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Key" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListLabelsResponse-domain_Label": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Label" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListNotificationsResponse-domain_UserNotification": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.UserNotification" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListThreadMessagesResponse-domain_Message": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Message" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListThreadParticipantsResponse-domain_ThreadParticipant": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.ThreadParticipant" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListThreadsResponse-domain_Thread": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Thread" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketImpactsResponse-domain_TicketImpact": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketImpact" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketLinksResponse-domain_TicketLinkView": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketLinkView" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketPrioritiesResponse-domain_TicketPriority": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketPriority" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketStatusTransitionsResponse-domain_TicketStatusTransition": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketStatusTransition" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketStatusesResponse-domain_TicketStatus": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketStatus" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketTypesResponse-domain_TicketType": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketType" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketUrgenciesResponse-domain_TicketUrgency": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.TicketUrgency" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.ListTicketsResponse-domain_Ticket": { "properties": { "count": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/domain.Ticket" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.PatchChannelRequest": { "properties": { "active": { "type": "boolean" }, "config": { "type": "object" }, "name": { "type": "string" } }, "type": "object" }, "v1.PatchChannelResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Channel" } }, "type": "object" }, "v1.PatchContactRequest": { "properties": { "description": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "mobile": { "type": "string" }, "phone": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "v1.PatchContactResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Contact" } }, "type": "object" }, "v1.PatchGroupMembersRequest": { "properties": { "members": { "items": { "$ref": "#/components/schemas/v1.PatchGroupMembersRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "members" ], "type": "object" }, "v1.PatchGroupMembersRequestItem": { "properties": { "contactId": { "type": "integer" }, "role": { "$ref": "#/components/schemas/domain.GroupMemberRole" } }, "required": [ "contactId", "role" ], "type": "object" }, "v1.PatchGroupMembersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/domain.GroupMember" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "v1.PatchGroupRequest": { "properties": { "description": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "v1.PatchGroupResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Group" } }, "type": "object" }, "v1.PatchLabelRequest": { "properties": { "assignmentContext": { "type": "string" }, "autoAssign": { "type": "boolean" }, "color": { "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "v1.PatchLabelResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Label" } }, "type": "object" }, "v1.PatchThreadMessageRequest": { "properties": { "content": { "type": "string" }, "contentType": { "type": "string" } }, "type": "object" }, "v1.PatchThreadMessageResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Message" } }, "type": "object" }, "v1.PatchTicketRequest": { "properties": { "agentId": { "type": "integer" }, "assigneeId": { "type": "integer" }, "contactId": { "type": "integer" }, "impactName": { "type": "string" }, "labels": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "priorityName": { "type": "string" }, "statusName": { "type": "string" }, "subject": { "type": "string" }, "typeName": { "type": "string" }, "urgencyName": { "type": "string" } }, "type": "object" }, "v1.PatchTicketResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.Ticket" } }, "type": "object" }, "v1.PatchTicketStatusRequest": { "properties": { "color": { "type": "string" }, "displayName": { "type": "string" }, "isDefault": { "type": "boolean" }, "position": { "type": "integer" } }, "type": "object" }, "v1.PatchTicketStatusResponse": { "properties": { "data": { "$ref": "#/components/schemas/domain.TicketStatus" } }, "type": "object" }, "v1.RemoveGroupMembersRequest": { "properties": { "members": { "items": { "$ref": "#/components/schemas/v1.RemoveGroupMembersRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "members" ], "type": "object" }, "v1.RemoveGroupMembersRequestItem": { "properties": { "contactId": { "type": "integer" } }, "required": [ "contactId" ], "type": "object" }, "v1.RemoveThreadParticipantsRequest": { "properties": { "participants": { "items": { "$ref": "#/components/schemas/v1.RemoveThreadParticipantsRequestItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "participants" ], "type": "object" }, "v1.RemoveThreadParticipantsRequestItem": { "properties": { "contactId": { "type": "integer" } }, "required": [ "contactId" ], "type": "object" }, "v1.RemoveTicketLinksRequest": { "properties": { "ticketIds": { "items": { "type": "integer" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "ticketIds" ], "type": "object" }, "v1.UploadAttachmentsError": { "properties": { "error": { "type": "string" }, "filename": { "type": "string" } }, "type": "object" }, "v1.UploadAttachmentsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/domain.Attachment" }, "type": "array", "uniqueItems": false }, "errors": { "items": { "$ref": "#/components/schemas/v1.UploadAttachmentsError" }, "type": "array", "uniqueItems": false } }, "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "description": "Static key for machine-to-machine access. Alternative to BearerAuth.", "in": "header", "name": "X-API-Key", "type": "apiKey" }, "BearerAuth": { "description": "Token issued by the central equipme authentication, sent as `Bearer \u003ctoken\u003e`.", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "", "url": "" }, "info": { "contact": { "name": "equipme GmbH" }, "description": "\u003e **Beta.** This API is not final. Endpoints, field names and response shapes can still change between\n\u003e releases, and not every resource is covered yet.\n\nSolvio is the AI-powered support ticketing and messaging part of the equipme platform. At its core, a\nticket is a **conversation** — a structured, collaborative thread between everyone involved in resolving\nan issue or task. The system is designed API-first, to support integrations and automation.\n\nEvery entity belongs to a **tenant**, and every operation is scoped to it. A resource outside the caller's\nscope is reported as `404`, never as `403` — the API does not reveal that it exists.\n\n## Authentication\n\nEvery `/v1` request needs one of these headers:\n\n| Header | Value | Use |\n| --- | --- | --- |\n| `Authorization` | `Bearer \u003ctoken\u003e` | Token issued by the central equipme authentication |\n| `X-API-Key` | `\u003ckey\u003e` | Static key for machine-to-machine access |\n\nSend one or the other. A request without a valid credential is answered with `401`.\n\n## Reading resources\n\n### `fields` — the shape of the response\n\nWithout `fields`, a resource is represented by its **scalar values**: its own data plus, for every\nreference it holds, the value that identifies it — `assigneeId` for a contact, `statusName` for a\nstatus. Related objects are never embedded by default.\n\n`fields` selects explicitly, and it drives the database read as well as the response, so asking for\nless is genuinely cheaper:\n\n| Selection | Response |\n| --- | --- |\n| `fields=subject,createdAt` | `id`, `subject`, `createdAt` |\n| `fields=assignee` | `id` plus the assignee's scalar values |\n| `fields=assignee.firstName,assignee.lastName` | `id` plus exactly those two |\n| `fields=labels(limit=5;sort=name)` | `id` plus the first five labels by name |\n\nAnything listed as a property of the resource's schema can be selected. Rules worth knowing:\n\n- `id` is returned first at every level, whether or not it was asked for.\n- A relation selected without sub-fields yields its own scalar values — the same rule that shapes the\n resource itself.\n- Fields are returned in the order they were requested.\n- A collection accepts `(limit=…;offset=…;sort=…)`; without a limit it returns at most 50 entries, and\n never more than 100.\n- An unknown field name is answered with `400`.\n\n### `filter` — a JSON expression\n\nA predicate is `{\"field\": …, \"op\": …, \"value\": …}`; `and`, `or` and `not` nest them. A field may be a\ndotted path into a filterable relation. Which fields a resource accepts is documented per endpoint;\nan unknown one is answered with `400`.\n\n```json\n{\"and\":[{\"field\":\"status.name\",\"op\":\"eq\",\"value\":\"in_progress\"},\n {\"field\":\"createdAt\",\"op\":\"gte\",\"value\":\"2026-03-01T00:00:00Z\"}]}\n```\n\nOperators: `eq`, `neq`, `contains`, `startsWith`, `endsWith`, `doesNotContain`, `in`, `notIn`, `gt`,\n`gte`, `lt`, `lte`, `isNull`, `isNotNull`.\n\n### `search` — free text\n\nThe term is used as a whole — leading and trailing spaces are trimmed, nothing else is split off —\nand matched case-insensitively as a substring. Which fields it reaches is decided per resource and\ndocumented at the endpoint; it commonly includes related people, so searching for a name finds the\ntickets of that person. A resource that does not offer a search ignores the parameter.\n\n### `sort` — ordered terms\n\nComma-separated `field:direction`, direction defaults to `asc`: `sort=priority.level:desc,createdAt`.\nA field may be `relation.field` for a to-one relation. Results always receive `id` as a final\ntie-breaker, so paging stays stable.\n\n### `offset` and `limit`\n\n`limit` has to be between 1 and 100 and defaults to 100. `count` in the response is the total number\nof matching rows, not the size of the page — use it to drive paging.\n\n## Changing resources\n\nA `PATCH` body is a **JSON merge patch** ([RFC 7396](https://datatracker.ietf.org/doc/html/rfc7396)),\nsent as `application/json`. Send only what should change — never the whole resource. Every field\ncarries one of three meanings:\n\n| The field is | Meaning |\n| --- | --- |\n| omitted | leave it as it is |\n| `null` | clear it |\n| a value | set it to that value |\n\n```json\n{\"assigneeId\": 17, \"priorityName\": null}\n```\n\nThat assigns the ticket and clears its priority. Everything else keeps its current value, so there is\nno read-modify-write cycle and no risk of writing back a field you never meant to touch.\n\nRules worth knowing:\n\n- **A relation is changed through the scalar that identifies it** — `assigneeId`, `statusName`,\n `typeName` — never by embedding the related object. A nested `assignee` object in the body is ignored.\n- **An array replaces the whole collection.** Merge patch does not merge arrays: `{\"labels\":[\"billing\"]}`\n leaves exactly one label, and both `{\"labels\":null}` and `{\"labels\":[]}` remove all of them. A label\n name that does not exist yet is created.\n- **A field that cannot be empty has no `null` form.** `statusName` and `subject` are always set, so an\n explicit `null` there leaves the current value unchanged instead of clearing it.\n- A status change is validated against the configured transitions and answered with `400` when the\n transition is not permitted.\n- The response carries the patched resource under `data`.\n\n## Errors\n\nEvery failing request answers with the same envelope:\n\n```json\n{\n \"error\": {\n \"code\": \"NOT_FOUND\",\n \"message\": \"human-readable description of what went wrong\"\n }\n}\n```\n\n| Status | `code` |\n| --- | --- |\n| 400 | `BAD_REQUEST` |\n| 401 | `UNAUTHORIZED` |\n| 403 | `FORBIDDEN` |\n| 404 | `NOT_FOUND` |\n| 409 | `CONFLICT` |\n| 500 | `INTERNAL` |\n\nMatch on `code` — it is stable. `message` is written for humans and its wording is not part of the\ncontract. `details` is present only where an error carries structured context, such as the resource a\nconflict collided with.\n", "title": "Solvio REST API", "version": "1.0.0-beta" }, "openapi": "3.1.0", "paths": { "/v1/attachments": { "get": { "description": "Returns the attachments of a thread. `threadId` is required — attachments are never listed across\nthreads.\n\n**Filterable** — `id`, `threadId`, `messageId`, `creatorId`, `name`, `contentType`, `size`,\n`inline`, `composing`, `createdAt`.\n\n**Sortable** — `id`, `name`, `size`, `createdAt`.\n\n**Searchable** — nothing yet; use `filter` with `contains` on `name`.\n", "operationId": "listAttachments", "parameters": [ { "description": "Thread id", "example": 8801, "in": "query", "name": "threadId", "required": true, "schema": { "type": "integer" } }, { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,size,contentType", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListAttachmentsResponse-domain_Attachment" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List the attachments of a thread", "tags": [ "attachment" ] }, "post": { "description": "Uploads one or more files as `multipart/form-data` under the field name `files`.\n\nEither `threadId` names the thread the files belong to, or `composing=true` marks them as not yet\nbound to a thread — in that case `tenantId` says where they live. Without one of the two the request\nis answered with `400`.\n\nBecause several files travel in one request, the answer distinguishes three outcomes:\n\n| Status | Meaning |\n| --- | --- |\n| `201` | every file was stored; `data` holds them |\n| `207` | some were stored, some were not; `errors` names the failures per file |\n| `422` | none could be stored |\n\nAn entry in `errors` carries the `filename` and what went wrong, so a client can retry exactly those.\n", "operationId": "uploadAttachments", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "title": "files", "type": "file" }, { "example": 8801, "title": "threadId", "type": "integer" }, { "title": "tenantId", "type": "integer" }, { "title": "composing", "type": "boolean" } ] } }, "multipart/form-data": { "schema": { "type": "object" } } }, "description": "Files to upload; repeat for several | Thread the files belong to | Tenant, required while composing | Upload without binding to a thread yet" }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.UploadAttachmentsResponse" } } }, "description": "Created" }, "207": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.UploadAttachmentsResponse" } } }, "description": "Some files were stored, some were not" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Upload attachments", "tags": [ "attachment" ] } }, "/v1/attachments/{id}": { "delete": { "description": "Deletes an attachment and its stored file. A file that a message already refers to disappears from\nthat message. Answers with `204` and no body.\n", "operationId": "deleteAttachment", "parameters": [ { "description": "Attachment id", "example": 4501, "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Delete an attachment", "tags": [ "attachment" ] } }, "/v1/attachments/{id}/download": { "get": { "description": "Streams the file. The response is the file itself, not JSON — `Content-Type` is what the attachment\nwas stored as, and `Content-Disposition` carries its name.\n\nThe same file is also served under `/v1/attachments/{id}/download/{filename}`, where the trailing\nsegment is cosmetic: it lets a browser save the file under a readable name without a further round\ntrip. Any name works, the file is chosen by its id. Attachment bodies are never cached by\nintermediaries.\n", "operationId": "downloadAttachment", "parameters": [ { "description": "Attachment id", "example": 4501, "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Name to save the file under", "in": "path", "name": "filename", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "type": "file" } } }, "description": "OK" }, "400": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Download an attachment", "tags": [ "attachment" ] } }, "/v1/channels": { "get": { "description": "Returns the tenant's channels, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `tenantId`, `name`, `kind`, `purpose`, `active`, `createdAt`, `updatedAt`.\n\n**Sortable** — `id`, `name`, `active`, `createdAt`, `updatedAt`.\n\n**Searchable** — nothing yet.\n\nThe identities of a channel are not part of the default answer; request them with\n`fields=identities`.\n", "operationId": "listChannels", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,kind,purpose,active", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListChannelsResponse-domain_Channel" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List channels", "tags": [ "channel" ] }, "post": { "description": "Creates a channel. `name`, `kind` and `purpose` are required, `config` is validated against the\npurpose and rejected with `400` when it does not fit.\n\nToday only `EMAIL` with a conversational purpose (`THREAD` or `TICKET`) can be created — any other\nkind is answered with `400`. Inbound email additionally requires the server to have its mail domain\nconfigured.\n\n`active` decides whether the channel is used; an inactive channel keeps its configuration but neither\nsends nor receives.\n", "operationId": "addChannel", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddChannelRequest", "summary": "request", "description": "Channel to create" } ] } } }, "description": "Channel to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddChannelResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Create a channel", "tags": [ "channel" ] } }, "/v1/channels/{channelId}": { "delete": { "description": "Deletes a channel. Threads that were bound to it keep their messages; they simply have no transport\nany more, so nothing further is delivered for them. Answers with `204` and no body.\n", "operationId": "deleteChannel", "parameters": [ { "description": "Channel id", "example": 3, "in": "path", "name": "channelId", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Delete a channel", "tags": [ "channel" ] }, "get": { "description": "Returns a single channel by its id. Its identities are not included unless `fields=identities` asks\nfor them.\n", "operationId": "getChannel", "parameters": [ { "description": "Channel id", "example": 3, "in": "path", "name": "channelId", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "name,kind,identities", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetChannelResponse-domain_Channel" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a channel", "tags": [ "channel" ] }, "patch": { "description": "Changes a channel. The body follows JSON Merge Patch semantics: an absent field stays as it is, `null`\nclears it, a value sets it.\n\n`kind` and `purpose` cannot be changed — they decide what the channel *is*, and its configuration and\nidentities depend on them. A replacement `config` is validated against the existing purpose.\n", "operationId": "patchChannel", "parameters": [ { "description": "Channel id", "example": 3, "in": "path", "name": "channelId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchChannelRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchChannelResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change a channel", "tags": [ "channel" ] } }, "/v1/channels/{channelId}/identities": { "post": { "description": "Gives a channel an address. `direction` is `INBOUND` for the address messages arrive at and `OUTBOUND`\nfor the one they are sent from; `type` is `EMAIL`, `PHONE`, `TOKEN` or `URL`, and `value` is the\naddress itself.\n\nAn **outbound** address that is not a `URL` may only be used once the tenant has proven that it owns\nit: without a verified claim on that address the request is answered with `403`. Inbound addresses\ncarry no such requirement.\n\nA channel holds at most one identity per direction — adding a second one for the same direction\nreplaces it. The answer is the channel, so the caller sees the result in one step.\n", "operationId": "addChannelIdentity", "parameters": [ { "description": "Channel id", "example": 3, "in": "path", "name": "channelId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddChannelIdentityRequest", "summary": "request", "description": "Address to bind" } ] } } }, "description": "Address to bind", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddChannelIdentityResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Give a channel an address", "tags": [ "channel_identity" ] } }, "/v1/channels/{channelId}/identities/{direction}": { "delete": { "description": "Takes an address away from a channel. The direction in the path says which one — `INBOUND` or\n`OUTBOUND`. The answer is the channel without that identity.\n\nA channel without an inbound identity receives nothing; without an outbound one it cannot send.\n", "operationId": "deleteChannelIdentity", "parameters": [ { "description": "Channel id", "example": 3, "in": "path", "name": "channelId", "required": true, "schema": { "type": "integer" } }, { "description": "INBOUND or OUTBOUND", "example": "OUTBOUND", "in": "path", "name": "direction", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.DeleteChannelIdentityResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Take an address away from a channel", "tags": [ "channel_identity" ] } }, "/v1/contacts": { "get": { "description": "Returns the tenant's contacts, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `tenantId`, `kind`, `title`, `firstName`, `lastName`, `email`, `phone`,\n`mobile`, `description`, `autoAssign`, `assignmentContext`, `createdAt`, `updatedAt`.\n\n**Sortable** — `id`, `firstName`, `lastName`, `email`, `phone`, `mobile`, `createdAt`, `updatedAt`.\n\n**Searchable** — nothing yet; use `filter` with `contains` on `firstName`, `lastName` or `email`.\n\nFiltering by `kind` separates people from the group faces: `{\"field\":\"kind\",\"op\":\"eq\",\"value\":\"PERSON\"}`.\n", "operationId": "listContacts", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "firstName,lastName,email", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListContactsResponse-domain_Contact" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List contacts", "tags": [ "contact" ] }, "post": { "description": "Creates a contact of kind `PERSON`. Every field is optional — a contact with nothing but an email\naddress is valid, and so is one with only a name, because contacts are often created from whatever an\ninbound message revealed. `email` is checked for a valid address when it is given.\n\nGroup faces cannot be created here; they come into being with their group.\n", "operationId": "addContact", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddContactRequest", "summary": "request", "description": "Contact to create" } ] } } }, "description": "Contact to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddContactResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Create a contact", "tags": [ "contact" ] } }, "/v1/contacts/{contactId}": { "get": { "description": "Returns a single contact by its id.\n\nA contact outside the caller's tenant is answered with `404`, the same as an id that does not exist.\n", "operationId": "getContact", "parameters": [ { "description": "Contact id", "example": 17, "in": "path", "name": "contactId", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "firstName,lastName,email", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetContactResponse-domain_Contact" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a contact", "tags": [ "contact" ] }, "patch": { "description": "Changes a contact. The body follows JSON Merge Patch semantics: an absent field stays as it is,\n`null` clears it, a value sets it.\n\nThe kind cannot be changed — a person does not become a group face.\n", "operationId": "patchContact", "parameters": [ { "description": "Contact id", "example": 17, "in": "path", "name": "contactId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchContactRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchContactResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change a contact", "tags": [ "contact" ] } }, "/v1/groups": { "get": { "description": "Returns the tenant's groups, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `tenantId`, `name`, `description`.\n\n**Sortable** — `id`, `name`.\n\n**Searchable** — nothing yet; use `filter` with `contains` on `name`.\n", "operationId": "listGroups", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,description", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListGroupsResponse-domain_Group" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List groups", "tags": [ "group" ] }, "post": { "description": "Creates a group together with its group contact, in one transaction — the group is routable from the\nmoment it exists.\n\n`email` and `phone` belong to that contact and are how the group is reached from the outside.\n`autoAssign` opens the group to automatic ticket routing; when it is switched on, `assignmentContext`\nhas to describe what the group is responsible for, otherwise the request is answered with `400` — the\nclassification reads that text.\n", "operationId": "addGroup", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddGroupRequest", "summary": "request", "description": "Group to create" } ] } } }, "description": "Group to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddGroupResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Create a group", "tags": [ "group" ] } }, "/v1/groups/{groupId}": { "delete": { "description": "Deletes a group along with its group contact.\n\nA group that still has **tickets assigned** to it is refused with `409` — reassign them first.\nHistoric thread participation of the group contact is detached automatically, so a group that merely\ntook part in past conversations can be removed.\n", "operationId": "deleteGroup", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Delete a group", "tags": [ "group" ] }, "get": { "description": "Returns a single group by its id. A group of another tenant is answered with `404`.\n", "operationId": "getGroup", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "name,description", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetGroupResponse-domain_Group" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a group", "tags": [ "group" ] }, "patch": { "description": "Changes a group. The body follows JSON Merge Patch semantics: an absent field stays as it is, `null`\nclears it, a value sets it. `email` and `phone` are applied to the group contact.\n", "operationId": "patchGroup", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchGroupRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchGroupResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change a group", "tags": [ "group" ] } }, "/v1/groups/{groupId}/members": { "delete": { "description": "Removes members from a group. Contacts that do not belong to it are ignored, so the request is\nidempotent, and it answers with `204` and no body.\n\nRemoving a member takes away the visibility that membership granted; the tickets themselves are\nuntouched.\n", "operationId": "removeGroupMembers", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.RemoveGroupMembersRequest", "summary": "request", "description": "Members to remove" } ] } } }, "description": "Members to remove", "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Remove members from a group", "tags": [ "group_member" ] }, "get": { "description": "Returns who belongs to a group and in which role.\n\n**Filterable** — `groupId`, `contactId`, `role`.\n\n**Sortable** — `groupId`, `contactId`.\n\n**Searchable** — nothing yet.\n", "operationId": "listGroupMembers", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } }, { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "contactId,role", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListGroupMembersResponse-domain_GroupMember" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List the members of a group", "tags": [ "group_member" ] }, "patch": { "description": "Changes the role of members that already belong to the group. Only a group `ADMIN` — or someone with\nthe explicit permission — may do this.\n", "operationId": "patchGroupMembers", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchGroupMembersRequest", "summary": "request", "description": "Members to change" } ] } } }, "description": "Members to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchGroupMembersResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change member roles", "tags": [ "group_member" ] }, "post": { "description": "Adds members to a group. Each entry needs a `contactId` and a `role` of `ADMIN`, `MEMBER` or\n`OBSERVER`, and every contact has to belong to the same tenant as the group.\n\nA contact that is already a member is **left as it is** — the request succeeds without changing that\nmember's role. Use the PATCH endpoint to change a role.\n", "operationId": "addGroupMembers", "parameters": [ { "description": "Group id", "example": 5, "in": "path", "name": "groupId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddGroupMembersRequest", "summary": "request", "description": "Members to add" } ] } } }, "description": "Members to add", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddGroupMembersResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Add members to a group", "tags": [ "group_member" ] } }, "/v1/keys": { "get": { "description": "Returns the tenant's API keys — their labels, actors and lifetimes, never their secrets.\n\n**Filterable** — `id`, `label`, `ident`, `actorId`, `creatorId`, `expiresAt`, `revokedAt`, `usedAt`,\n`createdAt`.\n\n**Sortable** — `id`, `label`, `ident`, `expiresAt`, `revokedAt`, `usedAt`, `createdAt`.\n\n**Searchable** — nothing yet.\n\n`usedAt` is when the key was last accepted and `revokedAt` when it was withdrawn — keys that are still\nusable are `{\"field\":\"revokedAt\",\"op\":\"isNull\"}`.\n", "operationId": "listKeys", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "label,expiresAt,usedAt", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListKeysResponse-domain_Key" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List API keys", "tags": [ "key" ] }, "post": { "description": "Issues an API key for an actor. `label` says what it is for, `actorId` whose permissions it carries,\nand `ttl` how long it lives — the default is 90 days and anything beyond a year is answered with\n`400`.\n\nThe answer contains `secret`, and this is the **only** time it is shown. Store it before closing the\nresponse; a lost secret cannot be recovered, only replaced by a new key.\n", "operationId": "addKey", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddKeyRequest", "summary": "request", "description": "Key to issue" } ] } } }, "description": "Key to issue", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddKeyResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Issue an API key", "tags": [ "key" ] } }, "/v1/labels": { "get": { "description": "Returns the tenant's labels, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `tenantId`, `name`, `description`, `color`, `autoAssign`,\n`assignmentContext`, `createdAt`, `updatedAt`.\n\n**Sortable** — `id`, `name`, `createdAt`, `updatedAt`.\n\n**Searchable** — nothing yet; use `filter` with `contains` on `name`.\n", "operationId": "listLabels", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,color", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListLabelsResponse-domain_Label" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List labels", "tags": [ "label" ] }, "post": { "description": "Creates labels — several at once, since they are usually set up as a set. Each entry needs a `name`,\nwhich identifies the label within the tenant.\n\nA name that already exists is **kept as it is**: the request succeeds and returns the existing label\nunchanged, rather than failing or overwriting its description and colour. Use `PATCH` to change one.\n", "operationId": "addLabels", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddLabelsRequest", "summary": "request", "description": "Labels to create" } ] } } }, "description": "Labels to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddLabelsResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Create labels", "tags": [ "label" ] } }, "/v1/labels/{labelId}": { "delete": { "description": "Deletes a label and detaches it from every ticket that carried it. The tickets themselves are\nuntouched. Answers with `204` and no body.\n", "operationId": "deleteLabel", "parameters": [ { "description": "Label id", "example": 12, "in": "path", "name": "labelId", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Delete a label", "tags": [ "label" ] }, "get": { "description": "Returns a single label by its id.\n", "operationId": "getLabel", "parameters": [ { "description": "Label id", "example": 12, "in": "path", "name": "labelId", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "name,color", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetLabelResponse-domain_Label" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a label", "tags": [ "label" ] }, "patch": { "description": "Changes a label. The body follows JSON Merge Patch semantics: an absent field stays as it is, `null`\nclears it, a value sets it.\n\nRenaming a label keeps it attached to its tickets — they refer to it by id, not by name.\n", "operationId": "patchLabel", "parameters": [ { "description": "Label id", "example": 12, "in": "path", "name": "labelId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchLabelRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchLabelResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change a label", "tags": [ "label" ] } }, "/v1/me": { "get": { "description": "Returns the calling user: their id, the tenant they are acting in, their username and the name and\nemail of their contact. It is the endpoint to call after signing in, to learn who and where you are.\n", "operationId": "getMe", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetMeResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Who am I", "tags": [ "me" ] } }, "/v1/notifications": { "get": { "description": "Returns the caller's own notification feed — one entry per notification that was addressed to them,\nnewest last unless `sort` says otherwise. Entries of other users are never returned, whatever the\nfilter says.\n\n**Filterable** — `id`, `userId`, `notificationId`, `readAt`.\n\n**Sortable** — `id`, `createdAt`.\n\n**Searchable** — nothing yet.\n\n`readAt` is when the caller marked the entry as read and is empty while it is unread — unread entries\nare `{\"field\":\"readAt\",\"op\":\"isNull\"}`. The notification behind an entry, with its status and delivery\nhistory, is fetched with `fields=notification`.\n", "operationId": "listNotifications", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "status,attempts,lastError", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListNotificationsResponse-domain_UserNotification" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List notifications", "tags": [ "notification" ] } }, "/v1/notifications/{id}": { "get": { "description": "Returns a single notification — the delivery itself, not a feed entry: which channel and address it\nwent to, how often it was attempted, when it was delivered and what the last error was.\n", "operationId": "getNotification", "parameters": [ { "description": "Notification id", "example": 9100, "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "status,attempts,lastError", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetNotificationResponse-domain_Notification" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a notification", "tags": [ "notification" ] } }, "/v1/notifications/{id}/retry": { "post": { "description": "Puts a failed delivery back into the queue: the notification is set to `PENDING`, its last error is\ncleared and the next attempt is scheduled immediately. Answers with `202`.\n\nOnly an **outbound** notification that has been given up on (`DEAD`) is taken back. Anything else is\nleft untouched — the request still answers with `202`, so check the notification afterwards if it\nmatters.\n", "operationId": "retryNotification", "parameters": [ { "description": "Notification id", "example": 9100, "in": "path", "name": "id", "required": true, "schema": { "type": "integer" } } ], "responses": { "202": { "description": "Accepted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Retry a failed delivery", "tags": [ "notification" ] } }, "/v1/permissions/check": { "post": { "description": "Asks whether the caller may perform given actions, several at once. Each request names a `domain`, a\n`resource` and an `action`; the answer repeats them with `allowed` next to each, in the same order.\n\nThis does not perform anything — it only reports the decision the API would make.\n", "operationId": "checkPermissions", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.CheckPermissionsRequest", "summary": "request", "description": "Decisions to ask for" } ] } } }, "description": "Decisions to ask for", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.CheckPermissionsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Check what the caller may do", "tags": [ "permission" ] } }, "/v1/threads": { "get": { "description": "Returns the threads the caller can read, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `externalId`, `tenantId`, `parentId`, `channelId`, `subject`, `description`,\n`status`, `createdAt`, `updatedAt`.\n\n**Sortable** — `id`, `externalId`, `subject`, `status`, `createdAt`, `updatedAt`.\n\n**Searchable** — `subject` and `description` of the thread, plus the email address, first name and\nlast name of **any** of its participants.\n", "operationId": "listThreads", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term across subject, description and participants", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "subject,status,createdAt", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListThreadsResponse-domain_Thread" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List threads", "tags": [ "thread" ] }, "post": { "description": "Opens a thread. `subject` is required; `parentId` nests the new thread under an existing one, and\n`description` is stored on the thread itself, not as a message.\n\nThe caller becomes the thread's `OWNER` and can post to it and manage its participants from then on.\n", "operationId": "addThread", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddThreadRequest", "summary": "request", "description": "Thread to open" } ] } } }, "description": "Thread to open", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddThreadResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Open a thread", "tags": [ "thread" ] } }, "/v1/threads/{threadId}": { "get": { "description": "Returns a single thread by its id.\n\nA thread the caller cannot reach at all is answered with `404`, the same as an id that does not\nexist. A thread that is visible but that the caller must not read is answered with `403`.\n", "operationId": "getThread", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "subject,status", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetThreadResponse-domain_Thread" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a thread", "tags": [ "thread" ] } }, "/v1/threads/{threadId}/messages": { "get": { "description": "Returns the messages of a thread, ordered by `id` unless `sort` says otherwise.\n\n**Filterable** — `id`, `threadId`, `authorId`, `replyToId`, `direction`, `originChannelId`,\n`originMessageId`, `createdAt`, `updatedAt`, and paths into the author, such as `author.lastName`.\n\n**Sortable** — `id`, `threadId`, `createdAt`, `updatedAt`.\n\n**Searchable** — nothing yet.\n\n`direction` tells where a message came from or is going: `INTERNAL` never leaves Solvio, `INBOUND`\narrived from an external channel, `OUTBOUND` is delivered through the thread's channel.\n", "operationId": "listThreadMessages", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } }, { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "content,createdAt,author.lastName", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListThreadMessagesResponse-domain_Message" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List the messages of a thread", "tags": [ "message" ] }, "post": { "description": "Posts a message to a thread. Requires write access, so an `OBSERVER` is answered with `403`.\n\n`content` is required and is interpreted as plain text; the format can be changed afterwards when\nthe message is edited. `replyToId` has to refer to a message of the same thread, and `attachmentIds`\nrefer to attachments uploaded beforehand.\n\nWhether the message stays internal or is delivered onward depends on the thread: a thread bound to a\ncommunication channel produces an `OUTBOUND` message to its participants, a thread without one\nproduces an `INTERNAL` message.\n", "operationId": "addThreadMessage", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddThreadMessageRequest", "summary": "request", "description": "Message to post" } ] } } }, "description": "Message to post", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddThreadMessageResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Post a message to a thread", "tags": [ "message" ] } }, "/v1/threads/{threadId}/messages/{messageId}": { "patch": { "description": "Edits a message. Only its **author** may do so — anyone else is answered with `403`, including a\nthread owner.\n\nAt least one of `content` and `contentType` has to be given, otherwise the request is answered with\n`400`. `contentType` accepts `text/plain` and `text/html` and decides how `content` is rendered.\n", "operationId": "patchThreadMessage", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } }, { "description": "Message id", "example": 52310, "in": "path", "name": "messageId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchThreadMessageRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchThreadMessageResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Edit a message", "tags": [ "message" ] } }, "/v1/threads/{threadId}/participants": { "delete": { "description": "Removes participants from a thread. Only an `OWNER` may do this. Contacts that do not take part are\nignored, so the request is idempotent, and it answers with `204` and no body.\n", "operationId": "removeThreadParticipants", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.RemoveThreadParticipantsRequest", "summary": "request", "description": "Participants to remove" } ] } } }, "description": "Participants to remove", "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Remove participants from a thread", "tags": [ "thread_participant" ] }, "get": { "description": "Returns who takes part in a thread and in which role.\n\n**Filterable** — `threadId`, `contactId`, `role`.\n\n**Sortable** — `threadId`, `contactId`, `role`.\n\n**Searchable** — nothing yet.\n", "operationId": "listThreadParticipants", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } }, { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "contactId,role", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListThreadParticipantsResponse-domain_ThreadParticipant" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List the participants of a thread", "tags": [ "thread_participant" ] }, "post": { "description": "Adds participants to a thread, or changes the role of those already on it — sending a contact that\nalready takes part updates its role rather than failing. Only an `OWNER` may do this.\n\nEach entry needs a `contactId` and a `role` of `OWNER`, `CONTRIBUTOR` or `OBSERVER`. Contacts have to\nbelong to the same tenant as the thread. If the same contact appears twice in one request, the\nstronger role wins.\n", "operationId": "addThreadParticipants", "parameters": [ { "description": "Thread id", "example": 8801, "in": "path", "name": "threadId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddThreadParticipantsRequest", "summary": "request", "description": "Participants to add" } ] } } }, "description": "Participants to add", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddThreadParticipantsResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Add participants to a thread", "tags": [ "thread_participant" ] } }, "/v1/ticket-impacts": { "get": { "description": "Returns the tenant's impact levels — how far a problem reaches. `level` ranks them, the higher the\nwider the reach; seeded as `low` (1), `medium` (2), `high` (3) and `critical` (4).\n\n**Filterable and sortable** — `name`, `displayName`, `level`, `color`, `createdAt`, `updatedAt`.\n\nThe list is read-only; the entries are seeded with the tenant.\n", "operationId": "listTicketImpacts", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,displayName,level", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketImpactsResponse-domain_TicketImpact" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List impact levels", "tags": [ "ticket_impact" ] } }, "/v1/ticket-priorities": { "get": { "description": "Returns the tenant's priorities — what to work on first. `level` ranks them, the higher the more\nimportant; seeded as `low` (1), `medium` (2), `high` (3) and `critical` (4).\n\nA ticket's priority is normally resolved from its impact and urgency rather than chosen directly.\n\n**Filterable and sortable** — `name`, `displayName`, `level`, `color`, `createdAt`, `updatedAt`.\n\nThe list is read-only; the entries are seeded with the tenant.\n", "operationId": "listTicketPriorities", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,displayName,level", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketPrioritiesResponse-domain_TicketPriority" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List priorities", "tags": [ "ticket_priority" ] } }, "/v1/ticket-status-transitions": { "delete": { "description": "Withdraws a permitted status change. The pair is named in the body rather than in the path, because a\ntransition is identified by its two ends. Tickets already in the target status are unaffected — only\nfuture moves are refused.\n", "operationId": "deleteTicketStatusTransition", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.DeleteTicketStatusTransitionRequest", "summary": "request", "description": "Status pair to withdraw" } ] } } }, "description": "Status pair to withdraw", "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Withdraw a permitted status change", "tags": [ "ticket_status_transition" ] }, "get": { "description": "Returns which status changes the tenant permits. A ticket may only move from one status to another if\na transition exists for that pair — `PATCH /v1/tickets/{ticketId}` answers with `400` otherwise.\n\n**Filterable** — paths into both ends, such as `sourceStatus.name` or `targetStatus.isDefault`.\n\n**Sortable** — `sourceStatus.\u003cfield\u003e` and `targetStatus.\u003cfield\u003e`, for example\n`sort=sourceStatus.position,targetStatus.position`.\n", "operationId": "listTicketStatusTransitions", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "sourceStatus.name,targetStatus.name", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketStatusTransitionsResponse-domain_TicketStatusTransition" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List permitted status changes", "tags": [ "ticket_status_transition" ] }, "post": { "description": "Permits a status change from `sourceStatusName` to `targetStatusName`. Both statuses have to exist\nand they have to differ, otherwise the request is answered with `400`. A transition that already\nexists is answered with `409`.\n\n`role` restricts the transition to a role; leaving it out lets it apply to everyone.\n", "operationId": "addTicketStatusTransition", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddTicketStatusTransitionRequest", "summary": "request", "description": "Status pair to permit" } ] } } }, "description": "Status pair to permit", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddTicketStatusTransitionResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Permit a status change", "tags": [ "ticket_status_transition" ] } }, "/v1/ticket-statuses": { "get": { "description": "Returns the tenant's ticket statuses.\n\n**Filterable and sortable** — `name`, `displayName`, `color`, `isDefault`, `position`, `createdAt`,\n`updatedAt`.\n\n`position` is the order they are meant to be shown in, `isDefault` marks the status a new ticket\nstarts in. Exactly one status is the default.\n", "operationId": "listTicketStatuses", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,displayName,position", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketStatusesResponse-domain_TicketStatus" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List ticket statuses", "tags": [ "ticket_status" ] }, "post": { "description": "Creates a ticket status. `name` identifies it from then on and `displayName` is what people see.\n\n`allowedSourceStatusNames` and `allowedTargetStatusNames` create the transitions in the same request:\nwhich statuses may lead into this one, and which ones it may lead to. Without them the new status is\nreachable from nowhere.\n\nSetting `isDefault` makes this the status new tickets start in and takes that role away from the\nstatus that held it.\n", "operationId": "addTicketStatus", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddTicketStatusRequest", "summary": "request", "description": "Status to create" } ] } } }, "description": "Status to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddTicketStatusResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Create a ticket status", "tags": [ "ticket_status" ] } }, "/v1/ticket-statuses/{name}": { "delete": { "description": "Deletes a ticket status. Three cases are refused with `400`:\n\n- the **default** status — assign a different default first,\n- the **last remaining** status,\n- a status **still used by tickets** without a `migrationTargetName`.\n\nWhen tickets still carry the status, `migrationTargetName` names the status they are moved to; it has\nto differ from the one being deleted. The move and the deletion happen together, so no ticket is ever\nleft without a status.\n", "operationId": "deleteTicketStatus", "parameters": [ { "description": "Status name", "example": "on_hold", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.DeleteTicketStatusRequest", "summary": "request", "description": "Where to move tickets that still carry the status" } ] } } }, "description": "Where to move tickets that still carry the status" }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Delete a ticket status", "tags": [ "ticket_status" ] }, "patch": { "description": "Changes a ticket status. The body follows JSON Merge Patch semantics: an absent field stays as it is,\n`null` clears it, a value sets it. The `name` cannot be changed — it is the identifier tickets refer\nto.\n\nSetting `isDefault` to `true` moves the default here and clears it on the status that held it.\nSetting it to `false` on the current default is answered with `400`: a tenant always has exactly one\ndefault, so assign a different one instead.\n", "operationId": "patchTicketStatus", "parameters": [ { "description": "Status name", "example": "in_progress", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchTicketStatusRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchTicketStatusResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change a ticket status", "tags": [ "ticket_status" ] } }, "/v1/ticket-types": { "get": { "description": "Returns the tenant's ticket types — what kind of request a ticket is. `position` is the order they\nare meant to be shown in.\n\n**Filterable and sortable** — `name`, `displayName`, `position`, `autoAssign`, `createdAt`,\n`updatedAt`.\n\nThe list is read-only; the entries are seeded with the tenant.\n", "operationId": "listTicketTypes", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,displayName", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketTypesResponse-domain_TicketType" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List ticket types", "tags": [ "ticket_type" ] } }, "/v1/ticket-urgencies": { "get": { "description": "Returns the tenant's urgency levels — how soon a ticket needs an answer. `level` ranks them, the\nhigher the more pressing; seeded as `low` (1), `medium` (2), `high` (3) and `critical` (4).\n\n**Filterable and sortable** — `name`, `displayName`, `level`, `color`, `createdAt`, `updatedAt`.\n\nThe list is read-only; the entries are seeded with the tenant.\n", "operationId": "listTicketUrgencies", "parameters": [ { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "name,displayName,level", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketUrgenciesResponse-domain_TicketUrgency" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List urgency levels", "tags": [ "ticket_urgency" ] } }, "/v1/tickets": { "get": { "description": "Returns the tickets the caller can read, ordered by `id` unless `sort` says otherwise. `count` is the\ntotal number of matching tickets, independent of `offset` and `limit`.\n\nThe grammar of `filter`, `search`, `sort` and `fields` is described in the introduction; what a ticket\naccepts for each of them is this:\n\n**Filterable** — `id`, `threadId`, `assigneeId`, `agentId`, `contactId`, `openerId`, `subject`,\n`summary`, `createdAt`, `updatedAt`, and paths into the taxonomy and the labels, such as\n`status.name`, `type.name`, `impact.level`, `priority.level`, `urgency.level` or `labels.name`.\n\n**Sortable** — `id`, `subject`, `summary`, `createdAt`, `updatedAt`, and `relation.field` for\n`assignee`, `agent`, `contact`, `status`, `type`, `impact`, `urgency` and `priority`, for example\n`sort=priority.level:desc,createdAt`.\n\n**Searchable** — `subject` and `summary` of the ticket, plus the email address, first name and last\nname of the contact it was raised for. So `search=lovelace` finds the tickets of that person without\nknowing their id.\n", "operationId": "listTickets", "parameters": [ { "description": "JSON filter expression", "example": "{\"field\":\"status.name\",\"op\":\"eq\",\"value\":\"in_progress\"}", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term across subject, summary and the contact", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "example": "priority.level:desc,createdAt", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "subject,statusName,assignee.lastName", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of tickets to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketsResponse-domain_Ticket" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List tickets", "tags": [ "ticket" ] }, "post": { "description": "Opens a ticket. A ticket always lives on a thread: pass `threadId` to open it on an existing\nconversation, or leave it out and a thread is created for it.\n\n`description` is required and becomes the ticket's opening message. `subject` is optional — when it\nis left out, a subject is generated from the description.\n\nThe status is taken from the tenant's default status; impact, urgency and priority are not accepted\nhere and stay unset until they are assigned. `typeName` refers to a ticket type by its name and may\nbe left out.\n", "operationId": "addTicket", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddTicketRequest", "summary": "request", "description": "Ticket to open" } ] } } }, "description": "Ticket to open", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddTicketResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Open a ticket", "tags": [ "ticket" ] } }, "/v1/tickets/{ticketId}": { "get": { "description": "Returns a single ticket by its id.\n\nTwo conditions have to hold, and they fail differently:\n\n- The ticket must be within the caller's scope. A ticket that is not — because it belongs to another\n tenant, or the caller has no path to it at all — is answered with `404`, the same as an id that does\n not exist.\n- The caller must be allowed to read it, either through the ticket's access graph (being a participant\n of its thread, or holding an identity grant for the assigned contact) or through an explicit\n permission. A ticket the caller can see but must not read is answered with `403`.\n", "operationId": "getTicket", "parameters": [ { "description": "Ticket id", "example": 4211, "in": "path", "name": "ticketId", "required": true, "schema": { "type": "integer" } }, { "description": "Selection of fields and relations", "example": "subject,statusName,assignee.lastName", "in": "query", "name": "fields", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.GetTicketResponse-domain_Ticket" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Get a ticket", "tags": [ "ticket" ] }, "patch": { "description": "Changes a ticket. The body follows JSON Merge Patch semantics, so every field has three states and\nthey mean different things:\n\n| The field is | Meaning |\n| --- | --- |\n| absent | leave it as it is |\n| `null` | clear it |\n| a value | set it |\n\nThe taxonomy fields — `statusName`, `typeName`, `impactName`, `urgencyName`, `priorityName` — refer\nto their entry by name, the same name the ticket returns when it is read. A status change is checked\nagainst the tenant's allowed transitions; a transition that is not permitted is answered with `400`.\n\n`labels` replaces the whole set: send the labels the ticket should carry afterwards, not the ones to\nadd. Names that do not exist yet are created.\n", "operationId": "patchTicket", "parameters": [ { "description": "Ticket id", "example": 4211, "in": "path", "name": "ticketId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.PatchTicketRequest", "summary": "request", "description": "Fields to change" } ] } } }, "description": "Fields to change", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.PatchTicketResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Change a ticket", "tags": [ "ticket" ] } }, "/v1/tickets/{ticketId}/links": { "delete": { "description": "Removes the links between this ticket and the given ones, in whichever direction they were recorded.\nTicket ids that are not linked are ignored. Answers with `204` and no body.\n", "operationId": "removeTicketLinks", "parameters": [ { "description": "Ticket id", "example": 4211, "in": "path", "name": "ticketId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.RemoveTicketLinksRequest", "summary": "request", "description": "Tickets to unlink" } ] } } }, "description": "Tickets to unlink", "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Unlink tickets", "tags": [ "ticket_link" ] }, "get": { "description": "Returns the tickets linked to this one, each with the link type as seen **from this ticket**.\n\n**Filterable** — `id`, `sourceTicketId`, `targetTicketId`, `relationType`, `creatorId`, `createdAt`.\n\n**Sortable** — `id`, `createdAt`.\n\n**Searchable** — nothing yet.\n", "operationId": "listTicketLinks", "parameters": [ { "description": "Ticket id", "example": 4211, "in": "path", "name": "ticketId", "required": true, "schema": { "type": "integer" } }, { "description": "JSON filter expression", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Free-text term — no effect here", "in": "query", "name": "search", "schema": { "type": "string" } }, { "description": "Comma-separated field:direction terms", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Selection of fields and relations", "example": "type,relatedTicket.subject", "in": "query", "name": "fields", "schema": { "type": "string" } }, { "description": "Number of entries to skip", "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer" } }, { "description": "Page size, 1 to 100", "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.ListTicketLinksResponse-domain_TicketLinkView" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "List the tickets linked to a ticket", "tags": [ "ticket_link" ] }, "post": { "description": "Links this ticket to others. Each entry names the `ticketId` to link and the `type` as seen from the\nticket in the path — the counterpart is recorded automatically for the other side.\n\nA ticket cannot be linked to itself; that is answered with `400`. Linking a pair that is already\nlinked does not duplicate the link.\n", "operationId": "addTicketLinks", "parameters": [ { "description": "Ticket id", "example": 4211, "in": "path", "name": "ticketId", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/v1.AddTicketLinksRequest", "summary": "request", "description": "Links to add" } ] } } }, "description": "Links to add", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1.AddTicketLinksResponse-domain_TicketLinkView" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Not Found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/middleware.ErrorResponse" } } }, "description": "Internal Server Error" } }, "summary": "Link tickets", "tags": [ "ticket_link" ] } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "servers": [ { "description": "The host serving this document", "url": "/api" } ], "tags": [ { "description": "A **thread** is the conversational container: it has a status (`OPEN` / `CLOSED`), an optional channel\nbinding, messages and participants, and it can be the parent of sub-threads.\n\nA **ticket** is the business-layer overlay on a thread. There is always exactly one thread per ticket, and\nthe ticket carries the assignee, agent, contact, opener, type, status and labels. Not every thread has a\nticket — free threads exist without one.\n", "name": "ticket", "x-displayName": "Ticket" }, { "description": "A **ticket link** connects two tickets and says how they relate. Links are directional and are always\nread from the perspective of the ticket in the path: linking A to B as `BLOCKS` means B shows the\nlink as `BLOCKED_BY`.\n\n| Link | Counterpart |\n| --- | --- |\n| `SUBTASK_OF` | `PARENT_OF` |\n| `BLOCKED_BY` | `BLOCKS` |\n| `DUPLICATE_OF` | `DUPLICATED_BY` |\n| `CAUSED_BY` | `CAUSES` |\n| `RELATES_TO` | `RELATES_TO` |\n", "name": "ticket_link", "x-displayName": "Ticket link" }, { "description": "A **thread** is the conversational container: it carries a status (`OPEN` / `CLOSED`), an optional\nbinding to a communication channel, its messages and its participants, and it can be the parent of\nsub-threads. A ticket is always attached to exactly one thread, but a thread can also exist on its\nown.\n\nAccess to a thread comes from taking part in it — the roles and what they permit are described under\n*Thread Participants*. Whoever creates a thread becomes its `OWNER`.\n", "name": "thread", "x-displayName": "Thread" }, { "description": "A **message** is one entry in a thread's conversation. Messages carry rich text and any number of\nattachments, and they are what actually travels to the outside world when a thread is bound to a\ncommunication channel.\n\n`direction` says where a message stands in that flow:\n\n| Direction | Meaning |\n| --- | --- |\n| `INTERNAL` | never leaves Solvio |\n| `INBOUND` | arrived from an external channel |\n| `OUTBOUND` | is delivered through the thread's channel |\n\nPosting requires write access to the thread; editing is reserved for the message's own author.\n", "name": "message", "x-displayName": "Message" }, { "description": "Participation is what grants access to a thread, and the role decides how far it reaches:\n\n| Role | May |\n| --- | --- |\n| `OWNER` | read, post messages, add and remove participants |\n| `CONTRIBUTOR` | read, post messages |\n| `OBSERVER` | read |\n\nAccess can also arrive without direct participation, through a group grant that conveys read or\nwrite. Managing participants is reserved for an `OWNER`.\n", "name": "thread_participant", "x-displayName": "Thread participant" }, { "description": "A **status** says where a ticket stands in its lifecycle. Statuses are defined per tenant and\nidentified by their `name`; `displayName` is the label meant for people and can be changed freely.\n\nExactly one status is the tenant's default — the one new tickets start in. `position` is the order\nthey are meant to be shown in.\n\nA ticket cannot move between arbitrary statuses: the permitted moves are defined as *Status\nTransitions*.\n", "name": "ticket_status", "x-displayName": "Ticket status" }, { "description": "A **transition** permits one status change: from a source status to a target status. A ticket may only\nmove where a transition exists — `PATCH /v1/tickets/{ticketId}` answers with `400` otherwise.\n\nTransitions are directional. Permitting `open → in_progress` does not permit the way back; that needs\nits own transition.\n", "name": "ticket_status_transition", "x-displayName": "Status transition" }, { "description": "A **ticket type** says what kind of request a ticket is — an incident, a question, a change. Types are\ndefined per tenant, identified by their `name`, and ordered for display by `position`.\n\nThey are seeded when a tenant is created and are read-only over the API for now.\n", "name": "ticket_type", "x-displayName": "Ticket type" }, { "description": "**Impact** says how far a problem reaches — one person, a department, the whole organisation. Levels\nare defined per tenant, identified by their `name` and ranked by `level`: the higher, the wider the\nreach.\n\nTogether with urgency, impact decides a ticket's priority.\n", "name": "ticket_impact", "x-displayName": "Impact level" }, { "description": "**Urgency** says how soon a ticket needs an answer. Levels are defined per tenant, identified by their\n`name` and ranked by `level`: the higher, the more pressing.\n\nTogether with impact, urgency decides a ticket's priority.\n", "name": "ticket_urgency", "x-displayName": "Urgency level" }, { "description": "**Priority** says what to work on first. Levels are defined per tenant, identified by their `name` and\nranked by `level`.\n\nA priority is normally not chosen but derived: when a ticket's impact or urgency changes and both are\nthen set, the priority is resolved from the tenant's impact × urgency matrix. Setting `priorityName`\non a ticket overrides that, and the chosen priority is left alone as long as neither axis is touched\nagain.\n", "name": "ticket_priority", "x-displayName": "Priority" }, { "description": "A **contact** is the face of a person or a group inside a tenant — who a ticket is for, who it is\nassigned to, who takes part in a thread. Contacts exist independently of accounts: someone can be a\ncontact without ever signing in.\n\nThree kinds exist, and only the first is created through these endpoints:\n\n| Kind | Where it comes from |\n| --- | --- |\n| `PERSON` | a real individual, created here or alongside a user account |\n| `GROUP` | the face of an internal group, created together with the group and never by hand |\n| `INTAKE` | external inbound entity, planned |\n", "name": "contact", "x-displayName": "Contact" }, { "description": "A **label** is a free tag on a ticket, defined per tenant and identified by its `name`. Tickets carry\nany number of them, and `PATCH /v1/tickets/{ticketId}` replaces the whole set at once.\n\n`autoAssign` opens a label to automatic classification: only labels with it switched on are\ncandidates, and then `assignmentContext` is what the classification reads — `description` stays the\nhuman-facing text.\n", "name": "label", "x-displayName": "Label" }, { "description": "A **group** is an internal team — support, second level, a department. Groups are what tickets get\nrouted to when no single person is meant to own them yet.\n\nCreating a group also creates its **group contact**: the face the group shows to the rest of the\nsystem, so a ticket can be assigned to the group the same way it is assigned to a person. That contact\nis managed with the group and never by hand.\n\nWho belongs to a group, and with which role, is described under *Group Members*.\n", "name": "group", "x-displayName": "Group" }, { "description": "Membership is what gives a team visibility over the tickets assigned to its group, and the role\ndecides how far it reaches:\n\n| Role | Meaning |\n| --- | --- |\n| `ADMIN` | manages the group's membership |\n| `MEMBER` | belongs to the group and sees its tickets |\n| `OBSERVER` | sees the group's tickets without belonging to it |\n", "name": "group_member", "x-displayName": "Group member" }, { "description": "A **channel** is how Solvio talks to the outside world — an email mailbox today, other transports\nlater. A thread bound to a channel delivers its messages through it and receives replies back into the\nsame conversation.\n\nTwo properties decide what a channel is:\n\n| | Values |\n| --- | --- |\n| `kind` | the transport: `EMAIL`, `WEBHOOK`, `TEAMS`, `SMS`, `WHATSAPP`, `WEBCHAT`, `NOTICE` |\n| `purpose` | what it is used for: `THREAD` and `TICKET` carry conversations, `NOTIFICATION` only sends out |\n\n`config` is a typed object per purpose — it holds static defaults such as the sender name a channel\nuses, never conditions. It is validated against the purpose when a channel is created or changed.\n\nOnly `EMAIL` channels with a conversational purpose can be created at the moment; every other kind is\nanswered with `400`. The addresses a channel uses are described under *Channel Addresses*.\n", "name": "channel", "x-displayName": "Channel" }, { "description": "A channel reaches the outside through its **addresses**: an `INBOUND` address is where messages\narrive, an `OUTBOUND` address is where they are sent from. A channel holds at most one of each.\n\nAn outbound address may only be used once the tenant has proven that it owns it.\n", "name": "channel_identity", "x-displayName": "Channel address" }, { "description": "An **attachment** is a file that belongs to a thread — uploaded first, then referenced when a message\nis posted. Uploads and messages are separate steps so that a file can be transferred while a message\nis still being written.\n\nAn attachment that is uploaded while composing carries `composing: true` and belongs to no message\nyet; posting a message with its id is what binds the two together.\n", "name": "attachment", "x-displayName": "Attachment" }, { "description": "A **notification** is one outbound or inbound delivery — an email that leaves the system because\nsomething happened on a ticket, or a message that arrived. They are created by the system, never by a\nclient; these endpoints exist to see what happened and to push a failed delivery back into the queue.\n\n| Status | Meaning |\n| --- | --- |\n| `PENDING` | waiting for its next attempt |\n| `DELIVERING` | being handed to the transport right now |\n| `DELIVERED` | done |\n| `DEAD` | given up on after repeated failures; `lastError` says why |\n", "name": "notification", "x-displayName": "Notification" }, { "description": "An **API key** lets a machine act without a user token. A key belongs to an actor: whatever it does,\nit does with that actor's permissions, and every request it makes is attributable.\n\nThe secret is shown **once**, in the answer to its creation, and is never retrievable afterwards —\nonly its hash is stored. Keys expire; a key without an explicit lifetime lasts 90 days, and no key may\nbe issued for longer than a year.\n", "name": "key", "x-displayName": "API key" }, { "description": "The permission endpoint answers what the calling user is allowed to do, so a client can decide what to\noffer before trying it.\n", "name": "permission", "x-displayName": "Permission" }, { "description": "Who the current credential belongs to.\n", "name": "me", "x-displayName": "Me" } ] }