انتقل إلى المحتوى الرئيسي
للمطوّرين

ابنِ على TManage API.

اربط أدواتك برمز وصول أو OAuth، والتزم بحدود الطلبات، واستقبل Webhooks موقّعة، واطّلع على كل نقاط النهاية.

المصادقة

كل طلب يُنفَّذ باسم عضو واحد في مساحة عمل واحدة، ويتحقق API من صلاحيات هذا العضو مع كل طلب.

رموز API

أنشئ رمزًا من الإعدادات ← رموز API، وأرسله بهذا الشكل: Authorization: Bearer tmanage_pat_… الرمز يعمل على مساحة عمل واحدة، ويمكنك إلغاؤه في أي وقت.

OAuth للتطبيقات

التطبيقات ومساعدات الذكاء الاصطناعي تتصل عبر OAuth 2.1 مع PKCE، والعضو يوافق على الصلاحيات: قراءة أو كتابة أو إدارة. صلاحية الفوترة لا تُضاف تلقائيًا أبدًا.

حدود الطلبات

عند تجاوز الحد، يرد API بالرمز 429 Too Many Requests ومعه header اسمه Retry-After. انتظر عدد الثواني المذكور فيه، ثم أعد المحاولة.

المسارات العامة
120 في الدقيقة و2,000 في الساعة لكل عنوان
مسارات الدخول والرموز
أكثر تشددًا، لكل عنوان
عند تجاوز الحد
429 مع Retry-After

الويب هوك

كل إرسال يكون موقّعًا. تحقّق من X-TManage-Signature (HMAC-SHA256 للطابع الزمني ومحتوى الطلب)، وارفض أي طابع زمني يختلف بأكثر من 5 دقائق.

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

مرجع API

كل نقاط النهاية في API، مقسّمة حسب المجال.

Organizations

  • POST/organizationscreateOrganization

    المعاملات

    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateOrganizationRequest

    الاستجابات

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

    المخططات

    CreateOrganizationRequest
    name: string · مطلوب
    timezone: string · مطلوب
    defaultLocale: en | ar · مطلوب
    Organization
    id: Id · مطلوب
    name: string · مطلوب
    slug: string · مطلوب
    timezone: string · مطلوب
    defaultLocale: string · مطلوب
    Error
    code: string · مطلوب
    message: string · مطلوب
    correlationId: Id · مطلوب
    fieldErrors: object

Projects

  • POST/organizations/{organizationId}/projectscreateProject

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateProjectRequest

    الاستجابات

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

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • projectId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    LinkClientOrganizationRequest

    الاستجابات

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

    المخططات

    LinkClientOrganizationRequest
    name: string · مطلوب
    approvalPolicy: all_required | any_one | ordered · مطلوب
    defaultInvitationExpiryDays: integer
    ClientOrganization
    id: Id · مطلوب
    organizationId: Id · مطلوب
    name: string · مطلوب
    Error
    code: string · مطلوب
    message: string · مطلوب
    correlationId: Id · مطلوب
    fieldErrors: object

ClientRequests

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • projectId · path · string (uuid) · مطلوب
    • cursor · query · string
    • status · query · ClientRequestStatus

    الاستجابات

    • 200 · ClientRequestPage Authorized requests

    المخططات

    ClientRequestPage
    items: ClientRequest[] · مطلوب
    nextCursor: string | null
  • POST/organizations/{organizationId}/projects/{projectId}/client-requestscreateClientRequest

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • projectId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateClientRequestRequest

    الاستجابات

    • 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.

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • requestId · path · string (uuid) · مطلوب

    الاستجابات

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

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • requestId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    TransitionClientRequest

    الاستجابات

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

    المخططات

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

Conversations

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • conversationId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateMessageRequest

    الاستجابات

    • 201 · Message Message committed and assigned a sequence

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • messageId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    ConvertMessageRequest

    الاستجابات

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

    المخططات

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

Work

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • projectId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateWorkItemRequest

    الاستجابات

    • 201 · WorkItem Work item created

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • workItemId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    UpdateWorkItemRequest

    الاستجابات

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

    المخططات

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

Files

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateUploadSessionRequest

    الاستجابات

    • 201 · UploadSession Scoped multipart upload session

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • uploadSessionId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CompleteUploadRequest

    الاستجابات

    • 202 · FileAsset Upload accepted for verification and scan

    المخططات

    CompleteUploadRequest
    parts: object[] · مطلوب
    FileAsset
    id: Id · مطلوب
    name: string · مطلوب
    status: created | uploading | uploaded | verifying | scanning | ready | rejected | expired | cancelled · مطلوب

Deliverables

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • projectId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateDeliverableRequest

    الاستجابات

    • 201 · Deliverable Deliverable created internal by default

    المخططات

    CreateDeliverableRequest
    title: string · مطلوب
    description: string
    Deliverable
    id: Id · مطلوب
    projectId: Id · مطلوب
    title: string · مطلوب
    status: string · مطلوب
  • POST/organizations/{organizationId}/deliverables/{deliverableId}/versionscreateDeliverableVersion

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • deliverableId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    CreateDeliverableVersionRequest

    الاستجابات

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

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • versionId · path · string (uuid) · مطلوب

    محتوى الطلب

    ClientPreviewRequest

    الاستجابات

    • 200 · ClientPreview Real-policy client projection plus warnings

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • versionId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    PublishDeliverableRequest

    الاستجابات

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

    المخططات

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

Approvals

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • approvalId · path · string (uuid) · مطلوب

    الاستجابات

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

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • approvalId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    ApprovalDecisionRequest

    الاستجابات

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

    المخططات

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

Awareness

  • GET/organizations/{organizationId}/homegetHome

    المعاملات

    • organizationId · path · string (uuid) · مطلوب

    الاستجابات

    • 200 · Home Permission-filtered My Day

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • cursor · query · string
    • mode · query · important | all | waiting_on_me | client_actions

    الاستجابات

    • 200 · InboxPage Recipient-only notification bundles

    المخططات

    InboxPage
    items: object[] · مطلوب
    nextCursor: string | null
  • GET/organizations/{organizationId}/searchsearch

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • q · query · string · مطلوب
    • type · query · string[]
    • cursor · query · string

    الاستجابات

    • 200 · SearchPage Authorized results only

    المخططات

    SearchPage
    items: object[] · مطلوب
    nextCursor: string | null

Administration

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • membershipId · path · string (uuid) · مطلوب

    الاستجابات

    • 200 · OffboardingImpact Ownership/access impact without executing changes

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • membershipId · path · string (uuid) · مطلوب
    • Idempotency-Key · header · string · مطلوب

    محتوى الطلب

    OffboardMemberRequest

    الاستجابات

    • 202 · OffboardingJob Membership suspended immediately; transfer workflow started

    المخططات

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب
    • cursor · query · string
    • action · query · string
    • actorId · query · string (uuid)

    الاستجابات

    • 200 · AuditPage Scope-redacted audit events

    المخططات

    AuditPage
    items: object[] · مطلوب
    nextCursor: string | null

Billing

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

    المعاملات

    • organizationId · path · string (uuid) · مطلوب

    الاستجابات

    • 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.

    المخططات

    OrganizationPlanUsage
    planCode: string · مطلوب
    planVersion: integer · مطلوب
    dimensions: UsageDimension[] · مطلوب
    clientUsersIncluded: boolean · مطلوب
    measuredAt: Timestamp · مطلوب
    Error
    code: string · مطلوب
    message: string · مطلوب
    correlationId: Id · مطلوب
    fieldErrors: object