support reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

GET /v1/support/threads

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Supply these values as query parameters. Path parameters remain in the URL.

{ environment?: "test" | "live" | undefined;
  status?: "open" | "resolved" | undefined;
  category?: "message" | "bug" | "feature" | undefined;
  needsReply?: "false" | "true" | undefined;
  unread?: "true" | undefined;
  labelId?: string | undefined;
  customerId?: string | undefined;
  projectId?: string | undefined;
  appId?: string | undefined;
  search?: string | undefined;
  limit?: unknown;
  cursor?: string | undefined;
  }

Validation schemas: supportThreadListQuerySchema in the downloadable schema registry.

Response

JSON response shape

SupportThreadPage

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleListCustomerSupportThreads.

POST /v1/support/threads

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ category: "message" | "bug" | "feature";
  subject: string;
  body: string;
  clientMessageId: string;
  email?: string | undefined;
  clientAccess?: { access: { version: 1;
  observedAt: string;
  policy: "account" | "app_store";
  verification: "unavailable" | "authoritative" | "verified_entitlements" | "cached";
  benefits: { identifier: string;
  source: "manual" | "apple" | "account" | "support_purchaser" | "preserved_import";
  effectiveUntil?: number | null | undefined;
  verifiedAt?: string | null | undefined;
  }[];
  truncated: boolean;
  providerEnvironment?: "Production" | "Sandbox" | "Xcode" | null | undefined;
  operationId?: string | null | undefined;
  attemptId?: string | null | undefined;
  requestId?: string | null | undefined;
  accessContextExpiresAt?: number | null | undefined;
  appleEvidence?: { observedAt: string;
  acquisition: "unavailable" | "rejected" | "app_transaction" | "receipt";
  purchaserComparison: "unavailable" | "first_observation" | "same" | "changed";
  collectionComplete: boolean;
  priorTransactionCount: number;
  submittedTransactionCount: number;
  retainedTransactionCount: number;
  missingProductIdentifiers: string[];
  previousPurchaserHash?: string | null | undefined;
  currentPurchaserHash?: string | null | undefined;
  acquisitionFailureStage?: string | null | undefined;
  } | null | undefined;
  };
  appleDiagnostics: { observedAt: string;
  stage: string;
  nativeDomain: string;
  nativeCode: number;
  storeKitCase?: string | null | undefined;
  underlying?: { domain: string;
  code: number;
  }[] | undefined;
  }[];
  } | undefined;
  diagnostics?: Record<string, string | number | boolean | null> | undefined;
  diagnosticsAvailable?: boolean | undefined;
  attachmentTokens?: string[] | undefined;
  }

Validation schemas: createSupportThreadRequestSchema in the downloadable schema registry.

Response

JSON response shape

SupportWriteResult

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleCreateCustomerSupportThread.

GET /v1/support/threads/:threadId

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: threadId (string). Every target must belong to the authenticated app or workspace.

Request

Use the path parameters above and any query options described below.

Handler inputs: path.threadId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

SupportThreadDetailResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetCustomerSupportThread.

POST /v1/support/threads/:threadId/messages

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: threadId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ body: string;
  clientMessageId: string;
  clientAccess?: { access: { version: 1;
  observedAt: string;
  policy: "account" | "app_store";
  verification: "unavailable" | "authoritative" | "verified_entitlements" | "cached";
  benefits: { identifier: string;
  source: "manual" | "apple" | "account" | "support_purchaser" | "preserved_import";
  effectiveUntil?: number | null | undefined;
  verifiedAt?: string | null | undefined;
  }[];
  truncated: boolean;
  providerEnvironment?: "Production" | "Sandbox" | "Xcode" | null | undefined;
  operationId?: string | null | undefined;
  attemptId?: string | null | undefined;
  requestId?: string | null | undefined;
  accessContextExpiresAt?: number | null | undefined;
  appleEvidence?: { observedAt: string;
  acquisition: "unavailable" | "rejected" | "app_transaction" | "receipt";
  purchaserComparison: "unavailable" | "first_observation" | "same" | "changed";
  collectionComplete: boolean;
  priorTransactionCount: number;
  submittedTransactionCount: number;
  retainedTransactionCount: number;
  missingProductIdentifiers: string[];
  previousPurchaserHash?: string | null | undefined;
  currentPurchaserHash?: string | null | undefined;
  acquisitionFailureStage?: string | null | undefined;
  } | null | undefined;
  };
  appleDiagnostics: { observedAt: string;
  stage: string;
  nativeDomain: string;
  nativeCode: number;
  storeKitCase?: string | null | undefined;
  underlying?: { domain: string;
  code: number;
  }[] | undefined;
  }[];
  } | undefined;
  diagnostics?: Record<string, string | number | boolean | null> | undefined;
  diagnosticsAvailable?: boolean | undefined;
  attachmentTokens?: string[] | undefined;
  }

Validation schemas: createSupportMessageRequestSchema in the downloadable schema registry.

Response

JSON response shape

SupportWriteResult

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleCreateCustomerSupportMessage.

POST /v1/support/threads/:threadId/read

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: threadId (string). Every target must belong to the authenticated app or workspace.

Request

No JSON body is required.

Handler inputs: path.threadId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

{ success: true;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleMarkCustomerSupportThreadRead.

POST /v1/support/threads/:threadId/resolve

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: threadId (string). Every target must belong to the authenticated app or workspace.

Request

No JSON body is required.

Handler inputs: path.threadId. Authentication values belong in headers; route IDs belong in the path.

Response

JSON response shape

SupportThreadDetailResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleResolveCustomerSupportThread.

GET /v1/support/contact

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

SupportContactResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetCustomerSupportContact.

PUT /v1/support/contact

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ email?: string | null | undefined;
  emailNotificationsEnabled?: boolean | undefined;
  pushNotificationsEnabled?: boolean | undefined;
  }

Validation schemas: updateSupportContactRequestSchema in the downloadable schema registry.

Response

JSON response shape

SupportContactResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleUpdateCustomerSupportContact.

POST /v1/support/attachments/prepare

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ fileName: string;
  contentType: string;
  byteSize: number;
  checksumSha256: string;
  }

Validation schemas: prepareSupportAttachmentUploadRequestSchema in the downloadable schema registry.

Response

JSON response shape

SupportAttachmentUploadPreparation

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handlePrepareCustomerSupportAttachment.

GET /v1/support/unread

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Request

Use the path parameters above and any query options described below.

Response

JSON response shape

{ unreadThreadCount: number;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleGetSupportUnreadSummary.

POST /v1/support/threads/:threadId/read-messages

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: threadId (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ messageIds: string[];
  }

Validation schemas: markSupportMessagesReadRequestSchema in the downloadable schema registry.

Response

JSON response shape

{ unreadThreadCount: number;
  success: boolean;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleMarkSupportMessagesRead.