Teambition

1. Overview

Teambition is Alibaba's enterprise collaboration and project management platform. It helps teams plan work, track tasks, manage projects, and coordinate members across organizations integrated with DingTalk and other enterprise systems.

Through GoInsight's Teambition node, you can integrate Teambition Open API operations into automated workflows. You can:

• Discover organization and project context (organization info, projects, members, user id mapping).
• Manage project membership (list, add, and remove project members).
• Work with tasks (create, update, search, count, archive or delete, and read task details).
• Resolve planning metadata (task types, stages, task groups, sprints, custom field definitions).
• Update custom field values on tasks when your template requires structured fields.

2. Prerequisites

Before using this node, you need a valid Teambition account and access to the target organization. Your Teambition Open Platform application must be authorized with scopes that cover the operations you call (projects, tasks, members, and directory reads). Some write operations may require an operator user id (OperatorId) per organization policy.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This Teambition node primarily operates on API Diagnostics, Custom Field Definition, Organization, Organization Member, Project, Project Member, Sprint, Stage, Task, Task Custom Field, Task Group, Task Type, and User Identity. The following table summarizes all supported operations:

Operation Details

Query Rate Limit and Errors

Summarizes Teambition open-platform rate-limit behavior and common JSON error-envelope patterns for client retry logic. An optional live probe mints an app credential token then performs a single read-only organization info request to capture diagnostic headers.

Options:

• IncludeLiveProbe (bool): When true, after minting the app JWT performs exactly one read-only organization info request and returns selected rate-limit-related response headers. When false (default), returns guidance text only without an extra upstream round trip.

Output:

• PlatformReference (object): Structured guidance: documentation entry reference, doc-center search topics, HTTP 429 throttling notes, JSON envelope keys used by Teambition Open API tools in this pack, and retry hints keyed by HTTP status.
• LiveProbe (object): When Include_Live_Probe is false: Performed=false and empty fields. When true: result of one read-only organization info probe including HttpStatus, SelectedHeaders (retry-after / x-ratelimit-* / x-request-id when present), and a short ResponseBodySnippet for debugging.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip or HTTP 429 on probe). False for validation and most 4xx errors.
• OriginalStatusCode (number): Upstream HTTP status from the live probe when performed; 0 when no probe or probe did not reach HTTP layer.
• StatusCode (number): Tool-level status code: 200=completed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Custom Field Definitions

Loads custom field definitions at project or organization scope so you can resolve field ids, types, and allowed value shapes.

Options:

• Resource (string): Which API to call: project (default) uses GET /v3/project/{projectId}/customfield/search; organization uses GET /v3/customfield/search for enterprise-level definitions.
• ProjectId (string): Teambition project id when Resource is project (path projectId). Obtain from Query_Projects. Ignored when Resource is organization unless you also use Org_Project_Ids for org search.
• OrgProjectIds (string): When Resource is organization, optional comma-separated project ids sent as query projectIds to narrow org-level definitions.
• Tql (string): Optional search string sent as query parameter q (Teambition custom-field search syntax per docs). Leave empty to omit.
• FilterScope (string): Optional query parameter scope on the project custom-field search endpoint only. Leave empty to omit.
• SfcId (string): Optional taskflow scenario id (sfcId) on the project search endpoint to filter definitions relevant to a task type. Leave empty to omit.
• PageToken (string): Pagination cursor from Pagination.NextPageToken of a previous successful response. Empty for first page.
• PageSize (number): pageSize query parameter; clamped 1..100. Default 50 for agent-friendly payloads.

Output:

• Definitions (object-array): Array of custom field definition objects from Teambition (shape follows GET customfield/search). Typical keys may include _id, name, type, choices — exact fields depend on API version and field type.
• Pagination (object): Pagination envelope: PageToken (input echo), NextPageToken (pass as Page_Token for next page), PageSize, Total (totalSize when provided, else -1), HasMore.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Organization Info

Reads organization profile metadata for the configured tenant using the linked Teambition app credential.

Output:

• Organization (object): Organization metadata from Teambition. Typical keys include _id, name, logo, description — exact fields depend on API version.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

List Organization Members

Lists enterprise (organization) members with cursor pagination so you can browse the directory and resolve userId or member identifiers across the tenant.

Options:

• PageToken (string): Cursor from a prior response Pagination.NextPageToken; leave empty for the first page.
• PageSize (number): Maps to pageSize on GET /api/org/member/list; use 0 to omit and let upstream defaults apply.
• MemberFilter (string): Optional filter query: initiate (new), disabled, enabled, external; empty string omits the parameter.
• RoleId (string): Optional organization role id; maps to roleId when non-empty.

Output:

• Members (object-array): Array of organization member objects (userId, memberId, name, email, role, etc. per API version).
• Pagination (object): Pagination: NextPageToken (non-empty means more pages), Total from upstream count when present, ReturnedCount, HasMore.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Query Organization Members

Queries Teambition enterprise (organization) members via the unified v3 endpoint POST /api/v3/member/query. Supports exact lookup by ids/employee numbers/phones/emails, fuzzy search by keyword (q), and secondary filters (labels, roleIds, roleLevels, isDisable) with cursor pagination.

Options:

• IdentifierList (object): Optional exact-lookup filters. When any list is non-empty, upstream ignores Keyword, AdditionalFilters.isDisable/roleIds/roleLevels, PageSize and PageToken.

Allowed keys (all strings, comma-separated supported):

• userIds
• employeeNumbers
• phoneNumbers
• emails

Example: {"userIds": "61e904617bb709319919590a"}

• Keyword (string): Optional free-text search mapped to q; matches name, English name, pinyin, email, phone, or employee number. Ignored by upstream when IdentifierList contains any non-empty list.
• PageSize (number): Optional page size 1-1000. Use 0 to omit and let the platform default apply. Ignored by upstream when an exact-lookup filter (UserIds/EmployeeNumbers/PhoneNumbers/Emails) is set.
• PageToken (string): Optional cursor from a prior Pagination.NextPageToken. Leave empty for the first page. Ignored by upstream when an exact-lookup filter is set.
• AdditionalFilters (object): Optional secondary filters merged into the POST URL query string (same transport as Keyword q, pageSize, pageToken; the JSON request body is not used for filters on this endpoint).

Allowed keys (all strings):

• labels (string): Comma-separated label names; a member is returned when its labels contain at least one match.
• labelMatch (string): Fuzzy label substring match.
• roleIds (string): Comma-separated role ids.
• roleLevels (string): Comma-separated values from -1 (external), 0 (member), 1 (admin), 2 (owner).
• isDisable (string): One of no (default, active only), yes (disabled only), or all.

Unknown keys are rejected with StatusCode=-1. Upstream ignores these filters when an exact-lookup filter (UserIds/EmployeeNumbers/PhoneNumbers/Emails) is provided.

Example: {"isDisable": "no", "roleLevels": "0,1,2"}

• OperatorId (string): Optional Teambition user id sent as X-Operator-Id (documented as the query person id). Leave empty to omit the header.

Output:

• Members (object-array): Array of organization member objects from Teambition v3 /api/v3/member/query. Each item contains: userId (string), name (string), roleId (string), role (integer: 2=owner, 1=admin, 0=member, -1=external), isDisabled (boolean), isResigned (boolean; equivalent to isDisabled), joined (ISO-8601 string), profile (object with birthday, city, country, email, phone, pinyin, position, province, staffType, employeeNumber), teamIds (array of department/team ids the member belongs to).
• Pagination (object): Pagination hints: NextPageToken (string; non-empty means more pages exist), ReturnedCount (integer; length of Members), HasMore (boolean; true when NextPageToken is non-empty). Pagination is ignored by upstream when an exact-lookup filter (UserIds/EmployeeNumbers/PhoneNumbers/Emails) is provided.
• Summary (string): One-line human-readable summary for agents with match count, sample names, and (when applicable) a note explaining that secondary filters were ignored because exact-lookup filters were supplied. Empty on failure.
• Hint (string): Actionable next step when the call failed (permission/404/rate-limit/5xx guidance). Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (network blips, 429 and 5xx are true; validation and most 4xx are false).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Diagnostic only; do not use to infer success/failure.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Primary success/failure signal. Empty string means SUCCESS; non-empty means FAILURE (contains reason and recovery hint).

Query Projects

Lists or searches Teambition projects for the tenant with paging and optional filters; extra filters can be merged through Additional_Query_Params.

Options:

• PageSize (number): Maximum projects per request. Teambition accepts pageSize; this tool clamps to 1..100. Default 50 for predictable pagination.
• PageToken (string): Opaque pagination token from a previous successful response field NextPageToken. Leave empty for the first page.
• ProjectIds (string): Comma-separated project ids to fetch (maps to query projectIds). Leave empty to list/filter by other fields.
• Name (string): Fuzzy match on project name (Teambition name query parameter).
• Visible (string): Visibility filter: project (private) or organization (enterprise-visible). Leave empty to omit the filter.
• IncludeTemplate (bool): When true, include template projects (includeTemplate=true). Default false.
• AdditionalQueryParams (object): Optional extra query parameters as an object with camelCase keys supported by Teambition project query (e.g. uniqueIdPrefix for project or task number prefix, sourceId for source project filter). Merged after pageSize, projectIds, name, pageToken, visible, and includeTemplate; your values override duplicates. Example: {"uniqueIdPrefix": "PROJ", "sourceId": "507f1f77bcf86cd799439011"}
• OperatorId (string): Optional X-Operator-Id header when your integration must attribute the call to an operator user id.

Output:

• Projects (object-array): Array of project objects from Teambition result. Typical keys: id, name, logo, description, organizationId, visibility, isTemplate, isArchived, isSuspended, uniqueIdPrefix, created, updated — exact schema depends on API version.
• NextPageToken (string): Pagination token for the next page when non-empty; pass as Page_Token (page_token) on the following call.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add Project Member

Adds existing organization directory users to a Teambition project so they gain project membership and appear on the project roster (Open API project member create-v2).

Input Parameters:

• ProjectId (string): Target Teambition project id. Required. Obtain from Query_Projects or the Teambition UI.
• UserIds (string): Comma-separated Teambition user ids to add to the project (required). Mapped to JSON body userIds. Users must already exist in the organization directory.

Options:

• OperatorId (string): Optional Teambition user id for X-Operator-Id when the organization requires an operator on member writes.
• AdditionalFields (object): Optional extra POST body fields using camelCase keys per Teambition Open API. Merged first; then userIds from User_Ids overrides any duplicate userIds key.

Output:

• Members (object-array): Array of project member rows returned in result after create-v2 (fields follow Open API; e.g. userId, memberId, roleId).
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

List Project Members

Lists project members with optional filters and paging so you can resolve user ids or roles inside a project.

Input Parameters:

• ProjectId (string): Teambition project id whose members will be listed. Obtain from project list APIs (e.g. Query_Projects) or the Teambition UI.

Options:

• UserIds (string): Optional comma-separated user ids to filter members when the API supports userIds.
• ProjectRoleId (string): Optional project role id filter when the API supports projectRoleId.
• PageSize (number): Optional pageSize query (cursor pagination); 0 omits the parameter so upstream defaults apply. Prefer 20-50 to bound token usage.
• PageToken (string): Optional pageToken for cursor pagination when the API returns nextPageToken.

Output:

• Members (object-array): Array of project member objects from Teambition. Typical keys may include user id, name, role — exact fields depend on API version.
• Pagination (object): Pagination hints: NextPageToken (cursor when present), Total (when upstream provides), ReturnedCount (length of Members), HasMore (true when NextPageToken is non-empty).
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Remove Project Member

Removes one or more users from a Teambition project via the Open API member delete path (requires tb-core:project.member:delete when enforced by the app). Use only after explicit human approval.

Input Parameters:

• ProjectId (string): Teambition project id to remove members from. Obtain from project list APIs (e.g. Query_Projects) or the Teambition UI.
• UserIds (string): Comma-separated Teambition user ids to remove from the project (maps to JSON userIds array). Resolve via List_Project_Members when possible.
• Confirm (bool): Must be true only after explicit human approval; prevents accidental agent-triggered membership removal.
• Reason (string): Non-empty audit string explaining why these members were removed, for compliance and post-incident review.

Options:

• OperatorId (string): Optional operator user id sent as x-operator-id when the API or org policy expects an acting user.

Output:

• ProjectId (string): Echo of the project id passed to the member delete path.
• RemovedUserIds (string-array): User ids returned in the upstream result array when the API returns string ids (empty when none or different shape).
• Errors (object-array): Upstream errors array when partial failures occur; empty on full success.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Query Sprints

Lists or searches sprints (iterations) for one Teambition project with paging and an optional text query.

Input Parameters:

• ProjectId (string): Teambition project id (path projectId). Obtain from Teambition_Query_Projects or project settings; must be a project the app can access under the same tenant.

Options:

• PageSize (number): Maximum sprints per request. Teambition accepts pageSize; this tool clamps to 1..100. Default 50 for predictable pagination.
• PageToken (string): Opaque pagination token from a previous successful response field NextPageToken. Leave empty for the first page.
• Query (string): Optional sprint search string sent as query parameter q when non-empty (filter semantics follow Teambition sprint search API documentation).
• OperatorId (string): Optional X-Operator-Id header when your integration must attribute the call to an operator user id.

Output:

• Sprints (object-array): Array of sprint objects from Teambition result. Typical keys may include _id, name, start, end, status — exact schema depends on API version.
• NextPageToken (string): Pagination token for the next page when non-empty; pass as Page_Token (page_token) on the following call.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search Stages

Search board stages (columns) for one project via GET .../project/{projectId}/stage/search.

Input Parameters:

• ProjectId (string): Teambition project id (path parameter). Obtain via Query Projects or the console.

Options:

• Q (string): Optional fuzzy keyword for stage/search when upstream supports query parameter q.
• PageSize (number): Optional pageSize for stage/search cursor pagination; 0 omits the parameter (upstream default).
• PageToken (string): Optional cursor from prior response NextPageToken for the next page of stage/search.
• OperatorId (string): Optional X-Operator-Id header when the integration must attribute the call to an operator user id.

Output:

• Stages (object-array): Board column / stage objects from Teambition stage/search (schema per API version; often includes _id/id and name/title).
• NextPageToken (string): Pass as PageToken on the next call when non-empty; empty when no further pages from upstream.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Teambition request. Default 0 means no upstream HTTP response was received (e.g., timeout).
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Archive or Delete Task

Archives a Teambition task to the recycle bin or permanently deletes it using the linked enterprise app credential. The workflow requires explicit end-user approval before execution.

Input Parameters:

• TaskId (string): Target Teambition task id to archive or delete. Obtain from the Teambition project task list or task detail Open API response fields such as _id or id.
• Operation (string): Which operation to run: archive (moves the task to the recycle bin) or delete (permanent removal). Allowed values: archive, delete.
• Confirm (bool): Safety gate set to true only after explicit human approval to archive or delete the task; prevents accidental agent-triggered removals when false.
• Reason (string): Non-empty audit string explaining why the archive or delete was approved, for compliance logs and post-incident review.

Output:

• Result (object): Parsed business payload from Teambition when JSON is returned (typically the result object). Empty object when the HTTP response has no body.
• TaskId (string): Echo of the task id that was sent to the archive or delete endpoint.
• Operation (string): Normalized operation that ran: archive or delete.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Count Project Tasks

Returns the total task count for one Teambition project, optionally narrowed with the same style of filters as task search.

Input Parameters:

• ProjectId (string): Teambition project id (path projectId). Obtain from project list APIs or the project URL. Required. Example: 507f1f77bcf86cd799439011.

Options:

• Query (string): Optional task filter string sent as HTTP query parameter q (same TQL-style expression language as task search). Leave empty to count all tasks under includeArchived rules. Operators include =, !=, >, >=, <, <=, and logical and / or; quote string literals. Example: isDone = false and executor = me(). Set Operator_Id when docs say the query depends on x-operator-id.
• IncludeArchived (bool): When true, include archived tasks in the count (includeArchived=true). Default false matches API default.
• OperatorId (string): Optional user id sent as x-operator-id when the query depends on the viewer context.

Output:

• TaskCount (number): Task count returned in API result (integer). 0 may be a valid count when the project has no matching tasks.
• RequestId (string): Upstream requestId when present (support / troubleshooting). Empty string if absent.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create Task

Creates a new task under a Teambition project using the linked app credential, with optional extra fields supplied through AdditionalFields.

Input Parameters:

• ProjectId (string): Target Teambition project id. Required. Obtain from Query_Projects or your project list.
• Content (string): Task title (content). Required. Non-empty string.

Options:

• ScenariofieldconfigId (string): Task type / scenario field config id when the project template requires it. Empty to omit. Use List_Task_Types to discover ids.
• TasklistId (string): Task list / grouping id when placing the task on a specific list. Empty to omit.
• StageId (string): Stage / column id when supported by the project template. Empty to omit.
• ExecutorId (string): Executor member user id on create. Empty to omit.
• OperatorId (string): Optional Teambition user id sent as X-Operator-Id; required by some enterprise create flows. Empty to omit.
• AdditionalFields (object): Optional extra fields for task creation using camelCase keys per Teambition Open API. Merged into the JSON body first; then projectId, content, scenariofieldconfigId, tasklistId, stageId, and executorId from mapped inputs override duplicate keys. Common keys: note (string), dueDate, startDate (UTC ISO-like strings), priority (number), parentTaskId, sprintId, involveMembers (array of member user id strings), tagIds (array of tag id strings), visible, storyPoint, taskflowStatusId. Example: {"note": "Ship v2", "dueDate": "2026-04-16T12:00:00.000Z", "priority": 2, "involveMembers": ["507f1f77bcf86cd799439099"]}

Output:

• Task (object): Created task from Teambition response (typically result); field names follow the Open API version.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed.
• UpstreamBodyPreview (string): When HTTP succeeds but no task id is parsed from the body, truncated upstream JSON (~8000 chars) for debugging. Empty otherwise.
• OriginalStatusCode (number): Upstream HTTP status code; 0 if no response received.
• StatusCode (number): Tool-level status: 200=request reached upstream and body parsed; -1=validation; 500=local/network error.
• ErrorMessage (string): Empty on success; otherwise failure reason from tool or upstream.

Get Task Detail

Loads one Teambition task by task id with fields and relationships for the tenant.

Input Parameters:

• TaskId (string): Teambition task id (Open API query parameter taskId). Obtain from project task list or integrations; must belong to a project the app can access under the same tenant.

Output:

• Task (object): Task detail object from Teambition. Typical keys include taskId, projectId, content, tasklistId, executorId, dueDate, isDone — exact fields depend on API version.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search Project Tasks

Lists or searches tasks within one Teambition project, including optional query text, paging, archived tasks, and operator attribution.

Input Parameters:

• ProjectId (string): Teambition project id (path projectId). Obtain it via Query_Projects (or another project listing action) for this X-Tenant-Id. Example format: a 24-hex style id from Teambition.

Options:

• Tql (string): Optional Teambition Query Language (TQL) expression sent as HTTP query parameter q; leave empty to omit q.

Supported operators:

• Comparison: =, !=, >, >=, <, <=
• Fuzzy match: ~ (substring contains)
• Logical combination: and, or
• Functions: me() (current operator), now() (current time)

Common task fields:

• executor: assignee user id
• content: task title
• isDone: completion status, true/false
• dueDate: ISO 8601 deadline
• priority: 0=none, 1=low, 2=medium, 3=high
• creator: creator user id

Combination examples:

• Incomplete tasks assigned to me: isDone = false and executor = me()
• High-priority unfinished: isDone = false and priority = 3
• Title contains keyword: content ~ "keyword"
• Due this week: dueDate >= "2026-04-21T00:00:00.000Z" and dueDate < "2026-04-28T00:00:00.000Z"

When using me() or other viewer-dependent expressions, also set Operator_Id so upstream can resolve the current user. See Teambition open documentation for the full operator and field list for your API version.

• IncludeArchived (bool): When true, include archived tasks in results. Default false: only active (non-archived) tasks are returned. The value is forwarded to the API as lowercase string "true"/"false" because the upstream is strict on boolean query typing.
• PageToken (string): Pagination cursor for retrieving the next page: copy the Pagination.NextPageToken value from a previous successful response into this field. Leave empty to fetch the first page.
• PageSize (number): Page size (maps to pageSize). Keep small (10–30) to reduce token consumption and improve agent response time; max 100.
• OperatorId (string): Optional Teambition user id (same 24-hex style as other ids) sent as header x-operator-id. Required when the TQL expression depends on the current operator context (e.g., contains me() or creator = me()); otherwise leave empty. Treat operator as the acting user on whose behalf Teambition resolves viewer-specific expressions.

Output:

• Tasks (object-array): Tasks returned for this page (array of Teambition task objects). Core fields:
• id (string): Task unique identifier.
• content (string): Task title.
• projectId (string): Parent project id.
• tasklistId (string): Parent tasklist id.
• stageId (string): Workflow stage id.
• executorId (string): Assignee user id (may be empty when unassigned).
• isDone (bool): Completion status.
• priority (number): 0=none, 1=low, 2=medium, 3=high.
• dueDate (string): ISO 8601 deadline (may be empty when no deadline).
• created (string): Creation timestamp (ISO 8601).
• updated (string): Last update timestamp (ISO 8601).

Additional fields depend on API version and project configuration.

• Pagination (object): Cursor pagination metadata (object):
• PageToken (string): Echo of request Page_Token.
• NextPageToken (string): Pass as Page_Token for the next page; empty string when no more pages.
• PageSize (number): Requested page size.
• Total (number): Total count from API totalSize, or -1 when API does not return it.
• HasMore (bool): True when NextPageToken is non-empty.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout).
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update Task

Applies a partial update to core Teambition task fields. Only non-empty mapped parameters (Content, Note, Due_Date, Start_Date, Executor_Id, Priority) and keys from Additional_Fields are sent; omitted fields are not included in the request body.

Input Parameters:

• TaskId (string): Target Teambition task id to update (required).

How to obtain:

• Call Search_Tasks or Get_Many_Tasks to list tasks and read the id field from the result.
• Call Get_Task_Details for a single task.

Format: 24-hex Mongo ObjectId string.

Example: 507f1f77bcf86cd799439011

Options:

• Content (string): New task title. Leave empty or omit to skip updating the title.

Example: Finalize Q1 marketing campaign

• Note (string): New task note / description (plain text). Leave empty or omit to skip.

Dedicated note endpoint: When only Note is provided (all other update fields empty), the tool calls PUT /api/v3/task/{taskId}/note; otherwise it calls PATCH /api/v3/task/{taskId} and updates all provided fields in one request.

Example: Updated requirements from client meeting on 2024-01-15

• DueDate (string): Task due datetime in UTC. Leave empty or omit to skip.

Format: ISO 8601 with trailing Z to denote UTC.

Examples:

• 2024-02-01T18:00:00Z (2024-02-01 18:00 UTC)
• 2024-12-31T23:59:59Z (last moment of the year)

Timezone note: Teambition requires UTC. If your local time is UTC+8 (Beijing), subtract 8 hours before sending. For example, Beijing 2024-01-15 18:00 becomes 2024-01-15T10:00:00Z.

• StartDate (string): Task start datetime in UTC. Leave empty or omit to skip.

Format: ISO 8601, e.g. 2024-01-20T09:00:00Z.

Timezone note: Must be UTC, same convention as Due_Date.

• ExecutorId (string): User id of the task executor. Leave empty or omit to skip updating the executor.

How to obtain:

• Call List_Project_Members and read userId or _id from the result.
• Call Query_Organization_Members for organization-level members.

Format: 24-hex Mongo ObjectId string.

Example: 507f1f77bcf86cd799439022

Clearing the executor: An empty string only means "do not modify". To clear the executor, use Additional_Fields: {"executorId": null} (refer to the Teambition Open API docs for whether null is accepted).

• Priority (number): Task priority as an integer. Leave empty or omit to skip.

Common values (actual range may vary by workspace configuration):

• 0: normal / none
• 1: low
• 2: medium
• 3: high
• 4: urgent

Example: 2 (medium)

Caveat: Because the type is number, 0 is treated as a valid value (sets priority to "normal"). To keep the current priority unchanged, omit this field entirely—do not send 0.

• AdditionalFields (object): Extra fields (key/value object) for attributes not covered by the mapped parameters above. Merged into the PATCH body first; the mapped parameters (Content, Note, Due_Date, Start_Date, Executor_Id, Priority) override duplicate keys.

Common business fields (camelCase):

• involveMembers (array): involved member ids
• tagIds (array): tag ids
• progress (number): task progress, 0-100
• tasklistId (string): task list id
• stageId (string): stage id
• taskflowStatusId (string): taskflow status id
• sprintId (string): sprint id
• visible (string): visibility (members / involves)
• storyPoint (number): story points
• isDone (boolean): completion flag

Advanced option (reserved key, NOT written to the request body):

• operatorId (string): operator user id. The tool extracts this key and sends it as the X-Operator-Id header for enterprise audit trails; some enterprise instances require it for write operations.

Example:

{"progress": 50, "isDone": false, "tasklistId": "507f1f77bcf86cd799439088", "operatorId": "507f1f77bcf86cd799439033"}

See the Teambition Open API docs for the full field list.

Output:

• Task (object): Teambition task object returned by the API (typically from the result field). May be an empty object when the upstream shape differs.

Common fields:

• id / _id (string): task id
• content (string): task title
• note (string): task note
• dueDate (string): due datetime (ISO 8601 UTC)
• startDate (string): start datetime (ISO 8601 UTC)
• executorId (string): executor user id
• priority (number): priority
• progress (number): progress, 0-100
• isDone (boolean): completion flag
• tasklistId / stageId / taskflowStatusId (string): task list / stage / taskflow status ids
• involveMembers (array): involved member ids
• tagIds (array): tag ids
• created / updated (string): creation / update timestamps

Field set may evolve with upstream API changes; additional keys not listed above may also be present.

• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed.
• OriginalStatusCode (number): Upstream HTTP status code; 0 if no response received.
• StatusCode (number): Tool-level status: 200=request reached upstream and body parsed; -1=validation; 500=local/network error.
• ErrorMessage (string): Empty on success; otherwise failure reason from tool or upstream.

Update Task Custom Field Values

Writes one custom field on a task using value, addValues, or delValues style payloads supported by the platform.

Input Parameters:

• TaskId (string): Teambition task id to update. Obtain from task list or detail APIs under the same X-Tenant-Id.
• CustomfieldId (string): Custom field id (cfId) for this task. Obtain from Teambition custom field definition APIs for the project or task template.
• FieldUpdate (object): Required custom field update payload wrapper.

Schema:

• mode: one of "set" | "add" | "del"
• values: non-empty array of objects; each object typically includes title and optionally metaString per Teambition custom field documentation.

Example: {"mode": "set", "values": [{"title": "In Progress"}]}

Options:

• DisableActivity (bool): When true, sends disableActivity=true so Teambition may skip creating feed activity for this change.
• DisableNotification (bool): When true, sends disableNotification=true to reduce notifications for this update.
• OperatorId (string): Optional X-Operator-Id header (user id acting on behalf of the app when your integration requires it).
• AdditionalFields (object): Optional object merged into the request body after lists; use only for documented extra keys. At least one mutation path (Value_Items, Add_Values, Del_Values, or value/addValues/delValues inside this object) is required.

Output:

• Result (object): Parsed result object from Teambition response; commonly includes updated timestamp string when successful.
• UpdatedAt (string): Convenience copy of result.updated when present (server-side update time string).
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying the same call may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search Task Groups

Search task groups (tasklists) for one project via GET .../project/{projectId}/tasklist/search.

Input Parameters:

• ProjectId (string): Teambition project id (path parameter). Obtain via Query Projects or the console.

Options:

• Q (string): Optional fuzzy keyword for tasklist/search when upstream supports query parameter q.
• PageSize (number): Optional pageSize for tasklist/search cursor pagination; 0 omits the parameter (upstream default).
• PageToken (string): Optional cursor from prior response NextPageToken for the next page of tasklist/search.
• TasklistIds (string): Optional comma-separated tasklist id filter forwarded as tasklistIds.
• OperatorId (string): Optional X-Operator-Id header when the integration must attribute the call to an operator user id.

Output:

• Tasklists (object-array): Task group / tasklist objects from Teambition tasklist/search (schema per API version).
• NextPageToken (string): Pass as PageToken on the next call when non-empty; empty when no further pages from upstream.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Teambition request. Default 0 means no upstream HTTP response was received (e.g., timeout).
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

List Task Types

Lists task type (scenario field config) identifiers for a project, or organization-wide defaults when project id is omitted.

Options:

• ProjectId (string): Teambition project id. When set, lists task types for that project (GET .../v3/project/{projectId}/scenariofieldconfig/search). Leave empty to search organization-level scenario field configs (GET .../v3/scenariofieldconfig/search).
• MaxItems (number): Maximum task type objects returned after fetch; upstream list is truncated to this count. Clamped 1..500; default 200 to keep agent context bounded.
• OperatorId (string): Optional X-Operator-Id header when the integration must attribute the call to an operator user id.

Output:

• TaskTypes (object-array): Array of scenario field config / task type objects from Teambition (field names follow open API version; often includes ids used when creating tasks).
• TotalCount (number): Count of task type records parsed from upstream before Max_Items truncation.
• Truncated (bool): True when upstream returned more records than Max_Items and TaskTypes was sliced.
• Summary (string): One-line human-readable summary for agents. Empty on failure.
• Hint (string): Actionable next step when the call failed. Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., network blip). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get DingTalk UserIds

Maps Teambition userIds to DingTalk enterprise userIds via the open platform id-mapping endpoint (GET /api/idmap/dingtalk/getDingUserId). Accepts up to 100 comma-separated Tb_User_Ids per call and also reports UnresolvedTbUserIds for ids the upstream did not return.

Input Parameters:

• TbUserIds (string): Required comma-separated Teambition userId list mapped to tbUserIds. Up to 100 ids per call; each id ≤ 64 chars. Obtain via List_Organization_Members, Query_Organization_Members, or Get_Task_Detail.

Output:

• Mappings (object-array): Array of {tbUserId, dingtalkUserId} objects mirrored from upstream result. dingtalkUserId example: manager4220.
• UnresolvedTbUserIds (string-array): Subset of input Tb_User_Ids that the upstream did not return (user missing, not in this org, or DingTalk account unlinked). Empty array means all inputs were resolved.
• RequestId (string): Upstream response requestId; share with Teambition support when filing issues. Empty if the call did not reach upstream.
• Summary (string): One-line human-readable summary for agents (resolved count, sample mappings, unresolved preview). Empty on failure.
• Hint (string): Actionable next step when the call failed (e.g., check tenant scopes, split large batches, retry after delay). Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., transient network/429/5xx). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Teambition UserIds

Maps DingTalk enterprise userIds to Teambition userIds via the open platform id-mapping endpoint (GET /api/idmap/dingtalk/getTbUserId). Accepts up to 50 comma-separated Ding_User_Ids per call and also reports UnresolvedDingUserIds for ids the upstream did not return.

Input Parameters:

• DingUserIds (string): Required comma-separated DingTalk enterprise userId list mapped to dingUserIds. Up to 50 ids per call; each id ≤ 128 chars (duplicates and Chinese commas are normalized). Example: "manager4220" or "manager4220,manager4221".

Output:

• Mappings (object-array): Array of {dingtalkUserId, tbUserId} objects mirrored from upstream result. dingtalkUserId example: manager4220; tbUserId is the Teambition user id.
• UnresolvedDingUserIds (string-array): Subset of input Ding_User_Ids that the upstream did not return (user missing, not in this org, or Teambition account unlinked). Empty array means all inputs were resolved.
• RequestId (string): Upstream response requestId; share with Teambition support when filing issues. Empty if the call did not reach upstream.
• Summary (string): One-line human-readable summary for agents (resolved count, sample mappings, unresolved preview). Empty on failure.
• Hint (string): Actionable next step when the call failed (e.g., check tenant scopes, split large batches, retry after delay). Empty on success.
• Retryable (bool): Whether retrying with the same parameters may succeed (e.g., transient network/429/5xx). False for validation and most 4xx errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Tool-level status code: 200=upstream request completed and response parsed (success depends on ErrorMessage), -1=local parameter validation error (do not retry), 500=local system/network/timeout/parse error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section walks through a workflow that creates a new task in a Teambition project.

Workflow Overview

Start -> Teambition: Create Task -> Answer

Step-by-Step Guide

1. Add Tool Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • Select the "Tools" tab in the panel that appears.
   • Find and select Teambition from the tools list.
   • Click Create Task to add the node to the canvas.
2. Configure Node:
   • Click the Create Task node to open its configuration panel.
   • Credential Configuration: Select your configured Teambition credentials at the top of the panel.
   • Parameter Entry:
   • ProjectId: The target project id. Run Query Projects first or copy the id from the Teambition UI.
   • Content: The task title (required, non-empty).
   • ScenariofieldconfigId (optional): Task type id when the project template requires it; use List Task Types to discover valid ids.
   • TasklistId (optional): Task list / grouping id when placing the task on a specific list.
   • StageId (optional): Workflow stage id; use Search Stages when your project uses stages.
   • ExecutorIds (optional): Comma-separated assignee user ids from List Organization Members or Query Organization Members.
   • AdditionalFields (optional): Extra POST body fields in camelCase per Teambition Open API.
3. Run and Verify:
   • When required fields are valid, run a test execution from the canvas.
   • Open the execution log and confirm TaskId, StatusCode, and an empty ErrorMessage on success.
   • Optionally run Get Task Detail with the returned task id to verify fields in Teambition.

Final Workflow Display

After configuration, a test run creates a task under the specified project. Downstream nodes can use outputs such as TaskId and Task for notifications or further updates.

6. FAQs

Q: Why do I get 401/403 or permission errors?

A: This usually indicates credential or scope issues. Check the following:

• App authorization: Confirm your Teambition app is installed for the organization and includes scopes for the API you call.
• Token validity: Regenerate or refresh credentials in GoInsight if the token expired.
• OperatorId: Some member write APIs require OperatorId when the organization enforces an operator header.

Q: How do I obtain ProjectId, user ids, or task list/stage ids?

A: Use discovery actions before writes:

• ProjectId: Query Projects.
• User ids: List Organization Members, Query Organization Members, Get Teambition UserIds, or Get DingTalk UserIds (when mapping from DingTalk).
• Task type / list / stage ids: List Task Types, Search Task Groups, Search Stages.

Q: Can retries create duplicate tasks?

A: Yes. Create Task is not strictly idempotent; a successful first call followed by a retry may create another task. Use caller-side deduplication keys in AdditionalFields where supported, or check existing tasks with Search Project Tasks before creating.

Q: What do StatusCode, ErrorMessage, and OriginalStatusCode mean?

A: GoInsight normalizes responses for agents:

• StatusCode 200: Request reached upstream and was parsed (still check ErrorMessage).
• StatusCode -1: Local validation error; fix parameters before retrying.
• StatusCode 500: Network, timeout, or parse errors; may be retryable when Retryable is true.
• OriginalStatusCode: Raw HTTP status from Teambition when available.

7. Official Documentation

For Teambition Open API details, refer to:

Teambition Open API Documentation