Skip to main content
DEVELOPERS

Build on the TManage API.

Connect your tools with a token or OAuth, stay inside the rate limits, receive signed webhooks and look up every endpoint.

Authentication

Every request acts as one member of one workspace. The API checks that member’s permissions on every call.

API tokens

Create a token in Settings, API tokens. Send it as Authorization: Bearer tmanage_pat_… A token reaches one workspace and can be revoked at any time.

OAuth for apps

Apps and AI assistants connect with OAuth 2.1 and PKCE. The member approves the scopes: read, write or manage. Billing is never included by default.

Rate limits

Over a limit, the API answers 429 Too Many Requests with a Retry-After header. Wait that many seconds, then try again.

Public routes
120 a minute, 2,000 an hour per address
Sign-in and token routes
Stricter, per address
Over the limit
429 with Retry-After

Webhooks

Each delivery is signed. Check X-TManage-Signature (HMAC-SHA256 of timestamp and body) and refuse a timestamp more than 5 minutes off.

X-TManage-Timestamp: 1767225600
X-TManage-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<body>")>
X-TManage-Event: work_item.created

API reference

Every endpoint of the contract, grouped by area.

Organizations

  • POST/organizationscreateOrganization

    Parameters

    • Idempotency-Key · header · string · required

    Request body

    CreateOrganizationRequest

    Responses

    • 201 · Organization Organization and owner membership created transactionally.
    • 400 · Error Invalid request or transition.
    • 409 · Error Version, state, or idempotency fingerprint conflict.

    Schemas

    CreateOrganizationRequest
    name: string · required
    timezone: string · required
    defaultLocale: en | ar · required
    Organization
    id: Id · required
    name: string · required
    slug: string · required
    timezone: string · required
    defaultLocale: string · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

Projects

  • POST/organizations/{organizationId}/projectscreateProject

    Parameters

    • organizationId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateProjectRequest

    Responses

    • 201 · Project Project created
    • 403 · Error Principal lacks capability; response does not reveal hidden object details.

    Schemas

    CreateProjectRequest
    workspaceId: Id · required
    name: string · required
    ownerUserId: Id · required
    targetAt: one of
    template: agency_delivery | software_studio | consulting_engagement
    Project
    id: Id · required
    organizationId: Id · required
    workspaceId: Id · required
    name: string · required
    ownerUserId: Id · required
    committedAt: one of
    forecastAt: one of
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object
  • POST/organizations/{organizationId}/projects/{projectId}/client-organizationslinkClientOrganization

    Parameters

    • organizationId · path · string (uuid) · required
    • projectId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    LinkClientOrganizationRequest

    Responses

    • 201 · ClientOrganization Client organization linked with explicit policy
    • 403 · Error Principal lacks capability; response does not reveal hidden object details.

    Schemas

    LinkClientOrganizationRequest
    name: string · required
    approvalPolicy: all_required | any_one | ordered · required
    defaultInvitationExpiryDays: integer
    ClientOrganization
    id: Id · required
    organizationId: Id · required
    name: string · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

ClientRequests

  • GET/organizations/{organizationId}/projects/{projectId}/client-requestslistClientRequests

    Parameters

    • organizationId · path · string (uuid) · required
    • projectId · path · string (uuid) · required
    • cursor · query · string
    • status · query · ClientRequestStatus

    Responses

    • 200 · ClientRequestPage Authorized requests

    Schemas

    ClientRequestPage
    items: ClientRequest[] · required
    nextCursor: string | null
  • POST/organizations/{organizationId}/projects/{projectId}/client-requestscreateClientRequest

    Parameters

    • organizationId · path · string (uuid) · required
    • projectId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateClientRequestRequest

    Responses

    • 201 · ClientRequest Request submitted; desired date is not committed
    • 403 · Error Principal lacks capability; response does not reveal hidden object details.
    • 422 · Error Invalid request or transition.

    Schemas

    CreateClientRequestRequest
    title: string · required
    description: object · required
    category: string
    urgencyReason: string
    desiredAt: one of
    fileAssetIds: Id[]
    ClientRequest
    id: Id · required
    projectId: Id · required
    title: string · required
    description: object
    status: ClientRequestStatus · required
    desiredAt: one of
    committedAt: one of
    clientSafeReason: string
    acceptedWorkItemId: one of
    version: integer · required
    createdAt: Timestamp · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object
  • GET/organizations/{organizationId}/client-requests/{requestId}getClientRequest

    Parameters

    • organizationId · path · string (uuid) · required
    • requestId · path · string (uuid) · required

    Responses

    • 200 · ClientRequest Client-safe or internal projection according to principal
    • 404 · Error Object absent or intentionally indistinguishable from inaccessible.

    Schemas

    ClientRequest
    id: Id · required
    projectId: Id · required
    title: string · required
    description: object
    status: ClientRequestStatus · required
    desiredAt: one of
    committedAt: one of
    clientSafeReason: string
    acceptedWorkItemId: one of
    version: integer · required
    createdAt: Timestamp · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object
  • POST/organizations/{organizationId}/client-requests/{requestId}/transitionstransitionClientRequest

    Parameters

    • organizationId · path · string (uuid) · required
    • requestId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    TransitionClientRequest

    Responses

    • 200 · ClientRequest Transition applied with audit event
    • 409 · Error Version, state, or idempotency fingerprint conflict.
    • 422 · Error Invalid request or transition.

    Schemas

    TransitionClientRequest
    toStatus: ClientRequestStatus · required
    expectedVersion: integer · required
    clientSafeReason: string
    committedAt: one of
    acceptedWork: one of
    ClientRequest
    id: Id · required
    projectId: Id · required
    title: string · required
    description: object
    status: ClientRequestStatus · required
    desiredAt: one of
    committedAt: one of
    clientSafeReason: string
    acceptedWorkItemId: one of
    version: integer · required
    createdAt: Timestamp · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

Conversations

  • POST/organizations/{organizationId}/conversations/{conversationId}/messagescreateMessage

    Parameters

    • organizationId · path · string (uuid) · required
    • conversationId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateMessageRequest

    Responses

    • 201 · Message Message committed and assigned a sequence

    Schemas

    CreateMessageRequest
    content: object · required
    parentMessageId: one of
    clientGeneratedId: string · required
    Message
    id: Id · required
    conversationId: Id · required
    authorUserId: Id · required
    sequenceNo: integer · required
    content: object · required
    audience: Audience · required
    createdAt: Timestamp · required
  • POST/organizations/{organizationId}/messages/{messageId}/convertconvertMessageToWork

    Parameters

    • organizationId · path · string (uuid) · required
    • messageId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    ConvertMessageRequest

    Responses

    • 201 · WorkItem Linked work item created without copying source context
    • 409 · Error Existing conversion returned or request fingerprint conflict

    Schemas

    WorkItem
    id: Id · required
    projectId: Id · required
    sourceMessageId: one of
    type: string · required
    title: string · required
    state: string · required
    ownerUserId: one of
    dueAt: one of
    audience: Audience · required
    version: integer · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

Work

  • POST/organizations/{organizationId}/projects/{projectId}/work-itemscreateWorkItem

    Parameters

    • organizationId · path · string (uuid) · required
    • projectId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateWorkItemRequest

    Responses

    • 201 · WorkItem Work item created

    Schemas

    CreateWorkItemRequest
    type: task | milestone | approval | request · required
    title: string · required
    state: backlog | ready | in_progress | blocked | internal_review | done | archived · required
    ownerUserId: one of
    dueAt: one of
    audience: Audience · required
    WorkItem
    id: Id · required
    projectId: Id · required
    sourceMessageId: one of
    type: string · required
    title: string · required
    state: string · required
    ownerUserId: one of
    dueAt: one of
    audience: Audience · required
    version: integer · required
  • PATCH/organizations/{organizationId}/work-items/{workItemId}updateWorkItem

    Parameters

    • organizationId · path · string (uuid) · required
    • workItemId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    UpdateWorkItemRequest

    Responses

    • 200 · WorkItem Updated with optimistic version increment
    • 409 · Error Version, state, or idempotency fingerprint conflict.

    Schemas

    UpdateWorkItemRequest
    expectedVersion: integer · required
    title: string
    state: string
    ownerUserId: one of
    dueAt: one of
    audience: Audience
    transitionReason: string
    WorkItem
    id: Id · required
    projectId: Id · required
    sourceMessageId: one of
    type: string · required
    title: string · required
    state: string · required
    ownerUserId: one of
    dueAt: one of
    audience: Audience · required
    version: integer · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

Files

  • POST/organizations/{organizationId}/upload-sessionscreateUploadSession

    Parameters

    • organizationId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateUploadSessionRequest

    Responses

    • 201 · UploadSession Scoped multipart upload session

    Schemas

    CreateUploadSessionRequest
    fileName: string · required
    mimeType: string · required
    sizeBytes: integer · required
    contentHash: string
    purpose: message_attachment | request_attachment | deliverable | document · required
    objectId: Id
    UploadSession
    id: Id · required
    expiresAt: Timestamp · required
    partSizeBytes: integer · required
    reservedBytes: integer · required
    uploadUrls: object[] · required
  • POST/organizations/{organizationId}/upload-sessions/{uploadSessionId}/completecompleteUploadSession

    Parameters

    • organizationId · path · string (uuid) · required
    • uploadSessionId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CompleteUploadRequest

    Responses

    • 202 · FileAsset Upload accepted for verification and scan

    Schemas

    CompleteUploadRequest
    parts: object[] · required
    FileAsset
    id: Id · required
    name: string · required
    status: created | uploading | uploaded | verifying | scanning | ready | rejected | expired | cancelled · required

Deliverables

  • POST/organizations/{organizationId}/projects/{projectId}/deliverablescreateDeliverable

    Parameters

    • organizationId · path · string (uuid) · required
    • projectId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateDeliverableRequest

    Responses

    • 201 · Deliverable Deliverable created internal by default

    Schemas

    CreateDeliverableRequest
    title: string · required
    description: string
    Deliverable
    id: Id · required
    projectId: Id · required
    title: string · required
    status: string · required
  • POST/organizations/{organizationId}/deliverables/{deliverableId}/versionscreateDeliverableVersion

    Parameters

    • organizationId · path · string (uuid) · required
    • deliverableId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    CreateDeliverableVersionRequest

    Responses

    • 201 · DeliverableVersion Immutable version created
    • 422 · Error Invalid request or transition.

    Schemas

    CreateDeliverableVersionRequest
    fileVersionIds: Id[] · required
    summary: string · required
    criteria: string[]
    DeliverableVersion
    id: Id · required
    deliverableId: Id · required
    versionNo: integer · required
    contentHash: string · required
    status: string · required
    publishedAt: one of
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object
  • POST/organizations/{organizationId}/deliverable-versions/{versionId}/client-previewpreviewClientProjection

    Parameters

    • organizationId · path · string (uuid) · required
    • versionId · path · string (uuid) · required

    Request body

    ClientPreviewRequest

    Responses

    • 200 · ClientPreview Real-policy client projection plus warnings

    Schemas

    ClientPreviewRequest
    clientOrganizationId: Id · required
    role: client_admin | client_reviewer | client_member | client_viewer · required
    ClientPreview
    projection: object · required
    warnings: object[] · required
    policyFingerprint: string · required
  • POST/organizations/{organizationId}/deliverable-versions/{versionId}/publishpublishDeliverableVersion

    Parameters

    • organizationId · path · string (uuid) · required
    • versionId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    PublishDeliverableRequest

    Responses

    • 201 · Approval Client projection and approval created transactionally
    • 422 · Error Invalid request or transition.

    Schemas

    PublishDeliverableRequest
    clientOrganizationId: Id · required
    reviewerUserIds: Id[] · required
    approvalPolicy: all_required | any_one | ordered · required
    dueAt: one of
    expectedContentHash: string · required
    policyFingerprint: string · required
    Approval
    id: Id · required
    deliverableVersion: DeliverableVersion · required
    contentHash: string · required
    status: draft | requested | viewed | approved | changes_requested | expired | cancelled | invalidated · required
    dueAt: one of
    reviewers: object[] · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

Approvals

  • GET/organizations/{organizationId}/approvals/{approvalId}getApproval

    Parameters

    • organizationId · path · string (uuid) · required
    • approvalId · path · string (uuid) · required

    Responses

    • 200 · Approval Reviewer-safe exact governed version
    • 404 · Error Object absent or intentionally indistinguishable from inaccessible.

    Schemas

    Approval
    id: Id · required
    deliverableVersion: DeliverableVersion · required
    contentHash: string · required
    status: draft | requested | viewed | approved | changes_requested | expired | cancelled | invalidated · required
    dueAt: one of
    reviewers: object[] · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object
  • POST/organizations/{organizationId}/approvals/{approvalId}/decisionsdecideApproval

    Parameters

    • organizationId · path · string (uuid) · required
    • approvalId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    ApprovalDecisionRequest

    Responses

    • 201 · ApprovalDecision Immutable reviewer decision
    • 409 · Error Version, state, or idempotency fingerprint conflict.
    • 422 · Error Invalid request or transition.

    Schemas

    ApprovalDecisionRequest
    decision: approved | changes_requested · required
    expectedContentHash: string · required
    feedback: object[]
    ApprovalDecision
    id: Id · required
    approvalId: Id · required
    reviewerUserId: Id · required
    decision: string · required
    contentHash: string · required
    decidedAt: Timestamp · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object

Awareness

  • GET/organizations/{organizationId}/homegetHome

    Parameters

    • organizationId · path · string (uuid) · required

    Responses

    • 200 · Home Permission-filtered My Day

    Schemas

    Home
    recommended: object[]
    due: WorkItem[]
    blocked: WorkItem[]
    waiting: object[]
  • GET/organizations/{organizationId}/inboxgetInbox

    Parameters

    • organizationId · path · string (uuid) · required
    • cursor · query · string
    • mode · query · important | all | waiting_on_me | client_actions

    Responses

    • 200 · InboxPage Recipient-only notification bundles

    Schemas

    InboxPage
    items: object[] · required
    nextCursor: string | null
  • GET/organizations/{organizationId}/searchsearch

    Parameters

    • organizationId · path · string (uuid) · required
    • q · query · string · required
    • type · query · string[]
    • cursor · query · string

    Responses

    • 200 · SearchPage Authorized results only

    Schemas

    SearchPage
    items: object[] · required
    nextCursor: string | null

Administration

  • GET/organizations/{organizationId}/members/{membershipId}/offboarding-impactgetOffboardingImpact

    Parameters

    • organizationId · path · string (uuid) · required
    • membershipId · path · string (uuid) · required

    Responses

    • 200 · OffboardingImpact Ownership/access impact without executing changes

    Schemas

    OffboardingImpact
    activeSessions: integer
    ownedWorkCount: integer
    pendingApprovalCount: integer
    externalShareCount: integer
    requiredTransferTypes: string[]
  • POST/organizations/{organizationId}/members/{membershipId}/offboardoffboardMember

    Parameters

    • organizationId · path · string (uuid) · required
    • membershipId · path · string (uuid) · required
    • Idempotency-Key · header · string · required

    Request body

    OffboardMemberRequest

    Responses

    • 202 · OffboardingJob Membership suspended immediately; transfer workflow started

    Schemas

    OffboardMemberRequest
    transferToUserId: Id · required
    confirmation: string · required
    OffboardingJob
    id: Id · required
    status: suspending | transferring | reviewing_external_access | completed | failed_partial · required
  • GET/organizations/{organizationId}/audit-eventslistAuditEvents

    Parameters

    • organizationId · path · string (uuid) · required
    • cursor · query · string
    • action · query · string
    • actorId · query · string (uuid)

    Responses

    • 200 · AuditPage Scope-redacted audit events

    Schemas

    AuditPage
    items: object[] · required
    nextCursor: string | null

Billing

  • GET/organizations/{organizationId}/billing/usagegetOrganizationPlanUsage

    Parameters

    • organizationId · path · string (uuid) · required

    Responses

    • 200 · OrganizationPlanUsage Authorized workspace plan and usage summary. Client principals and ordinary members cannot read billing data.
    • 403 · Error Principal lacks capability; response does not reveal hidden object details.

    Schemas

    OrganizationPlanUsage
    planCode: string · required
    planVersion: integer · required
    dimensions: UsageDimension[] · required
    clientUsersIncluded: boolean · required
    measuredAt: Timestamp · required
    Error
    code: string · required
    message: string · required
    correlationId: Id · required
    fieldErrors: object