> ## Documentation Index > Fetch the complete documentation index at: https://superthread.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a card > This endpoint allows you to create a new card in a specified team workspace by providing a set of required and optional parameters. Key required fields include: - `title`: The name of the card - `list_id`: The ID of the list where the card will be placed - `board_id` or `sprint_id`: One of these fields must be provided to specify where the card belongs to The card's content has a character limit of 102400, and timestamps like `due_date` and `start_date` are specified as Unix timestamps in seconds. Enum fields include status (committed, started, completed, cancelled) and icon types (image, emoji, icon). ## OpenAPI ````yaml POST /{team_id}/cards openapi: 3.0.0 info: description: Superthread Public API Specification version: '0.1' title: Public API contact: email: engineering@superthread.com servers: - url: https://api.superthread.com/v1 security: - BearerAuth: [] tags: - name: AI description: >- [Service: AI]. Handles AI-powered functionalities, such as recommendations, predictions, and automation features. - name: Activity description: >- [Service: Activity] Manages all activities; creating notifications and digests - name: Auth description: >- [Service: Auth] Responsible for user authentication, authorization, and session management. - name: Boards description: >- [Service: Boards] Manages core collaboration features such as "boards", "cards", "lists", "sprints", "epics". - name: Comments description: >- [Service: Comments] Handles the creation, editing, and management of comments across various entities. - name: Favourites description: >- [Service: Favourites] Responsible for favouriting resources in the system for quick access. - name: Files description: >- [Service: Files] Manages file uploads, storage, and retrieval for user and project resources. - name: Importer description: >- [Service: Importer] Handles data import operations from external sources into the platform. - name: Integrations description: >- [Service: Integrations] Facilitates connectivity with external tools and services, enabling smooth integration with third-party platforms and APIs. - name: Pages description: >- [Service: Pages] Manages the creation and organization of both public and private pages, supporting structured content and navigation and collaboration. - name: Projects description: '[Service: Projects] Handles all project related tasks.' - name: Reports description: >- [Service: Reports] Generates and manages analytical reports and insights for users and projects. - name: Search description: >- [Service: Search] Provides search functionalities, including indexing and retrieval of platform data. - name: TimeTracking description: >- [Service: TimeTracking] Manages time entries, active timers, time categories, billing rates, and audit/lock for time-tracking workflows. - name: Views description: >- [Feature] Provides tools to create and customize views, enabling users to organize and visualize their data according to their preferences and workflows. - name: OAuth2 description: >- [Feature] Supports OAuth2 integration for seamless user authentication and authorization, ensuring secure access to external APIs and services. - name: Sprints description: >- [Feature] Facilitates sprint management within agile workflows, including planning, progress tracking, and reporting. - name: Cards description: >- [Feature] A Card is the core concept used in the system to describe an individual task or work item. They are used across Boards, Sprints, and Roadmaps. Cards include features like descriptions, checklists, comments, priorities, tags and more. - name: Checklists description: >- [Feature] A Checklist is a list of items that need to be completed. It is used to track progress on a card. - name: Lists description: >- [Feature] Represents a collection of tasks or items grouped within different contexts in the system. Lists (externally referenced as "statuses") are utilized across various entities such as boards, sprints, and roadmaps. - name: Notes description: >- [Feature] Enables users to create, edit, and organize notes, supporting rich text, attachments, transcriptions and AI enhancements. - name: Tags description: >- [Feature] Groups endpoints related to the creation, retrieval, updating, deletion, and merging of tags within teams (workspaces). - name: Agents description: >- [Feature] Manages agents and runs. Provides CRUD operations for agents, launching cloud agents, monitoring agent status, retrieving conversations, and sending follow-ups. paths: /{team_id}/cards: parameters: - $ref: '#/components/parameters/path_team_id' post: tags: - Boards - Cards summary: Create a new card description: > This endpoint allows you to create a new card in a specified team workspace by providing a set of required and optional parameters. Key required fields include: - `title`: The name of the card - `list_id`: The ID of the list where the card will be placed - `board_id` or `sprint_id`: One of these fields must be provided to specify where the card belongs to The card's content has a character limit of 102400, and timestamps like `due_date` and `start_date` are specified as Unix timestamps in seconds. Enum fields include status (committed, started, completed, cancelled) and icon types (image, emoji, icon). operationId: createCard requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCardRequest' description: Card object that needs to be created required: true responses: '201': description: Card created content: application/json: schema: $ref: '#/components/schemas/CreateCardResponse' '402': description: | The workspace has reached its plan's limit on the number of cards it can have. Upgrade the workspace's plan or delete existing cards to free up capacity, then retry. content: application/json: schema: $ref: '#/components/schemas/PlanLimitError' default: description: client error content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/Error' components: parameters: path_team_id: in: path name: team_id description: >- Team ID is an alphanumerical string that identifies a Team. This is externally referred to as a "Workspace". required: true schema: type: string schemas: CreateCardRequest: type: object required: - title - list_id properties: title: type: string example: My Card nullable: false content: type: string example: Some card content x-omitempty: false maxLength: 102400 content_format: $ref: '#/components/schemas/ContentFormat' file_ids: type: array description: >- Existing file IDs to duplicate and associate with the created card. Use for files already uploaded to this workspace, such as files attached to an agent run. items: type: string schema: type: integer example: 1 nullable: true start_date: $ref: '#/components/schemas/STime' due_date: $ref: '#/components/schemas/STime' board_id: type: string example: '5' nullable: false project_id: type: string example: '1' nullable: false sprint_id: type: string example: '8' nullable: false list_id: type: string example: '114' nullable: false owner_id: type: string nullable: true members: type: array items: $ref: '#/components/schemas/AddMemberRequest' priority: type: integer minimum: 0 maximum: 4 example: 1 nullable: true estimate: type: integer example: 3 description: >- effort estimation enum for the card. 1 is least, 5 is greatest. will map to different values depending on project settings. minimum: 1 maximum: 5 nullable: true time_estimate_seconds: type: integer description: >- Original time estimate for the card in seconds (separate from the 0-5 effort `estimate` field). nullable: true time_remaining_seconds: type: integer description: >- Initial remaining time estimate in seconds. Defaults to `time_estimate_seconds` when omitted. nullable: true parent_card_id: type: string description: Optional card ID to set as parent nullable: true epic_id: type: string description: Optional epic ID to add card to nullable: true board_email_ref: type: string description: Optional Board Email reference when creating a card from an email example: b291eKoaaLn5 nullable: true user: $ref: '#/components/schemas/Actor' cover_image: $ref: '#/components/schemas/CoverImage' checklists: type: array description: Optionally specify checklist(s) to create and add to the card items: $ref: '#/components/schemas/AddChecklistRequest' nullable: true form_id: type: string description: ID of the form that created this card, if any x-omitempty: true form_requester_user_id: type: string description: ID of the user that created this card from form submission x-omitempty: true CreateCardResponse: type: object properties: card: $ref: '#/components/schemas/Card' PlanLimitError: type: object description: | Returned with HTTP 402 when the workspace's plan does not allow the requested action — typically because a per-workspace limit on the resource being created has been reached. The body includes the resource that was being created, the plan's limit on that resource, and the workspace's current usage, so the appropriate next step is usually to upgrade the workspace's plan or free up existing usage of that resource. required: - error - code - resource - limit - current - limit_kind properties: id: type: string example: err5f744ab code: type: integer format: int32 example: 402 sec: $ref: '#/components/schemas/SuperthreadErrorCode' message: type: string example: 'plan limit reached: board (25 of 25)' description: A user-friendly error message. date: $ref: '#/components/schemas/STime' error: type: string description: | Identifies the error class. Always `plan_limit_reached` for this response. enum: - plan_limit_reached example: plan_limit_reached resource: type: string description: The kind of resource the workspace was trying to create. example: board limit: type: integer description: The maximum number of this resource the workspace's plan allows. example: 25 current: type: integer description: The number of this resource the workspace currently has. example: 25 limit_kind: type: string description: | Identifies which limit was hit. Useful when more than one limit can apply to the same resource. example: boards_per_workspace Error: type: object properties: id: type: string example: err5f744ab code: type: integer format: int32 example: 403 sec: $ref: '#/components/schemas/SuperthreadErrorCode' message: type: string example: You do not have access to this resource description: A user-friendly error message date: $ref: '#/components/schemas/STime' ContentFormat: type: string description: >- Format of the content field. When set to 'markdown', the server converts the content from GitHub Flavored Markdown to HTML before storage. Defaults to 'html'. enum: - html - markdown default: html STime: type: integer format: int64 example: 1608742037016 description: unix timestamp in seconds x-go-type: type: STime import: package: github.com/superthread-com/common/pkg/types hints: noValidation: true kind: primitive AddMemberRequest: type: object properties: user_id: type: string example: u-dsu0j19 role: $ref: '#/components/schemas/MemberRole' Actor: title: Actor type: object description: describes a user or robot that created or updated a resource properties: user_id: type: string example: uDsu0j19 x-go-custom-tag: dynamodbav:",omitempty" type: type: string x-go-custom-tag: dynamodbav:",omitempty" example: user default: user enum: - user - robot - system nullable: false source: $ref: '#/components/schemas/ActorSource' CoverImage: allOf: - $ref: '#/components/schemas/Image' properties: positionY: type: number object_fit: type: string enum: - contain - cover nullable: true AddChecklistRequest: type: object properties: title: type: string example: My Checklist items: type: array items: $ref: '#/components/schemas/CreateChecklistItemRequest' Card: type: object properties: id: type: string example: '2700' type: type: string description: Type of the object being returned example: card icon: $ref: '#/components/schemas/Image' team_id: type: string example: tDsu0j19 title: type: string example: My Card content: type: string example: Some card content maxLength: 102400 schema: type: integer example: 1 description: Content schema version collaboration: $ref: '#/components/schemas/Collaboration' status: $ref: '#/components/schemas/CardStatus' priority: type: integer example: 1 board_id: type: string example: '12' board_title: type: string description: cached field list_id: type: string example: '41' list_color: type: string description: cached field list_title: type: string description: cached field sprint_id: type: string example: 4s12 owner_id: type: string example: uR2dws11 user_id: type: string example: uR2dws11 user_id_updated: type: string example: u2erXoQq user: $ref: '#/components/schemas/Actor' user_updated: $ref: '#/components/schemas/Actor' start_date: $ref: '#/components/schemas/STime' due_date: $ref: '#/components/schemas/STime' completed_date: $ref: '#/components/schemas/STime' time_created: $ref: '#/components/schemas/STime' time_updated: $ref: '#/components/schemas/STime' members: type: array items: $ref: '#/components/schemas/Member' checklists: type: array items: $ref: '#/components/schemas/Checklist' checklist_order: $ref: '#/components/schemas/Order' checklist_item_order: type: object additionalProperties: $ref: '#/components/schemas/Order' x-omitempty: false parent_card: $ref: '#/components/schemas/ParentCard' child_cards: type: array items: $ref: '#/components/schemas/ChildCard' child_card_order: $ref: '#/components/schemas/Order' linked_cards: type: array items: $ref: '#/components/schemas/LinkedCard' archived: $ref: '#/components/schemas/Archived' archived_list: type: boolean example: false description: whether the card is in an archived list archived_board: type: boolean example: false description: whether the card is in an archived board tags: type: array items: $ref: '#/components/schemas/Tag' total_comments: type: integer example: 3 x-omitempty: false total_files: type: integer example: 1 x-omitempty: false is_watching: type: boolean example: true description: whether current user is a watcher of this card x-go-custom-tag: dynamodbav:"-" is_bookmarked: type: boolean example: true description: whether current user has this card bookmarked x-go-custom-tag: dynamodbav:"-" project_id: type: string description: cached field external_links: type: array items: $ref: '#/components/schemas/ExternalLink' hints: type: array items: $ref: '#/components/schemas/CardHint' estimate: type: integer description: >- effort estimation enum for the card. 0 is unset, 1 is least, 5 is greatest. will map to different values depending on project settings. minimum: 0 maximum: 5 time_estimate_seconds: type: integer description: >- Original time estimate for the card in seconds (separate from the 0-5 effort `estimate` field). x-omitempty: true time_remaining_seconds: type: integer description: >- Remaining time estimate in seconds. Auto-decremented when time entries are logged; can be manually adjusted via the card update endpoint. x-omitempty: true epic: $ref: '#/components/schemas/EpicBrief' cover_image: $ref: '#/components/schemas/CoverImage' copied_from_card_id: type: string description: ID of the card that this card was copied from x-omitempty: true form_id: type: string description: ID of the form that created this card, if any x-omitempty: true form_values: type: object description: >- Submitted form values keyed by form field ID. Used by the portal to derive dynamic submission summaries. additionalProperties: type: string x-omitempty: true suggested_branch_name: type: string description: Suggested git branch name derived from the card ID and title x-go-custom-tag: dynamodbav:"-" SuperthreadErrorCode: type: string description: | Superthread Error Code (`SEC`): A structured error code. Format: `SEC:{ServiceID}-{InternalErrorCode}`. - `SEC`: Prefix for all structured error codes. - `ServiceID`: First 3 characters identify the service, '000' is reserved for generic errors. - `InternalErrorCode`: the next (last) 5 characters define the specific error. pattern: ^SEC:\d{3}-\d{5}$ example: SEC:000-00014 MemberRole: type: string enum: - admin - member - viewer ActorSource: title: ActorSource type: object description: describes the source of an actor properties: type: type: string example: oauth enum: - oauth - import - email - agent client_id: type: string x-go-custom-tag: dynamodbav:",omitempty" description: client ID if the resource was created via oauth2 app example: oczapier import_id: type: string x-go-custom-tag: dynamodbav:",omitempty" description: import ID if the resource was created by an import example: bf1b9f76-3f95-42fc-bd7f-050b2f5f4197 agent_id: type: string x-go-custom-tag: dynamodbav:",omitempty" description: agent ID if the resource was created by an agent example: bf1b9f76-3f95-42fc-bd7f-050b2f5f4197 email_addr: type: string x-go-custom-tag: dynamodbav:",omitempty" description: email address if the resource was created via an email example: somebody@example.com email_verified: type: boolean x-go-custom-tag: dynamodbav:",omitempty" description: whether the email sender was verified example: false on_behalf_of: type: string x-go-custom-tag: dynamodbav:",omitempty" description: >- User ID of the human responsible for this action. For trigger-initiated agent actions, this is the trigger creator. For mention/chat-initiated actions, this is the user who invoked the agent. Image: type: object required: - type - src properties: type: type: string enum: - image - icon - emoji nullable: false id: type: string description: Unique identifier for the image (optional). src: type: string example: >- data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg== description: >- Depending on the type this can be a URL, base64 image data, emoji unicode or an icon name nullable: false blurhash: type: string example: LEHV6nWB2yk8pyoJadR*.7kCMdnj x-go-custom-tag: dynamodbav:",omitempty" color: type: string example: black x-go-custom-tag: dynamodbav:",omitempty" emoji: type: string example: thumbsup description: Emoji string ID x-go-custom-tag: dynamodbav:",omitempty" CreateChecklistItemRequest: type: object properties: title: type: string example: Some title nullable: false content: type: string example: Some description checked: type: boolean description: checked state of the item. defaults to false. example: false Collaboration: type: object properties: token: type: string description: Security token used to start a collaboration session CardStatus: type: string enum: - committed - started - completed - cancelled example: started Member: type: object properties: user_id: type: string example: u-dsu0j19 x-go-custom-tag: diff:"user_id,identifier" assigned_date: $ref: '#/components/schemas/STime' role: $ref: '#/components/schemas/MemberRole' Checklist: type: object properties: id: type: string example: '232' x-go-custom-tag: diff:"id,identifier" title: type: string example: My Checklist content: type: string example: Some description card_id: type: string example: '32' user_id: type: string example: uG2sdaOn time_created: $ref: '#/components/schemas/STime' time_updated: $ref: '#/components/schemas/STime' items: type: array items: $ref: '#/components/schemas/ChecklistItem' Order: type: object description: string array representing an order of IDs x-go-type: type: Order import: package: github.com/superthread-com/common/pkg/types hints: noValidation: true kind: primitive x-omitempty: true nullable: true ParentCard: type: object properties: title: type: string example: Implement service requirements card_id: type: string example: '42' x-go-custom-tag: diff:"card_id,identifier" list_color: type: string status: $ref: '#/components/schemas/CardStatus' ChildCard: type: object properties: title: type: string example: Create illustration for upcoming holidays card_id: type: string example: '42' x-go-custom-tag: diff:"card_id,identifier" user_id: type: string example: us4Fsfed project_id: type: string example: '3' board_id: type: string example: '15' board_title: type: string example: Ideas list_id: type: string example: '55' list_title: type: string example: Done list_color: type: string status: $ref: '#/components/schemas/CardStatus' archived: $ref: '#/components/schemas/Archived' LinkedCard: type: object properties: title: type: string example: Create illustration for upcoming holidays card_id: type: string example: '42' x-go-custom-tag: diff:"card_id,identifier" user_id: type: string example: '42' project_id: type: string example: '3' board_id: type: string example: '15' board_title: type: string example: Ideas list_id: type: string example: list 1 list_title: type: string example: list 1 status: $ref: '#/components/schemas/CardStatus' archived: $ref: '#/components/schemas/Archived' linked_card_type: $ref: '#/components/schemas/LinkedCardType' icon: $ref: '#/components/schemas/Image' Archived: type: object properties: user_id: type: string example: uDsu0j19 time_archived: $ref: '#/components/schemas/STime' Tag: type: object properties: id: type: string example: u-dsu0j19 x-go-custom-tag: diff:"id,identifier" team_id: type: string example: u-dsu0j19 project_id: type: string example: '5' name: type: string example: todo slug: type: string example: todo color: $ref: '#/components/schemas/TagColor' total_cards: type: integer description: number of cards that use this tag example: 17 ExternalLink: type: object properties: type: $ref: '#/components/schemas/ExternalLinkType' github_pull_request: $ref: '#/components/schemas/GithubPullRequest' generic: $ref: '#/components/schemas/GenericExternalLink' CardHint: type: object properties: type: type: string description: defines the type of hint enum: - tag - relation example: tag tag: $ref: '#/components/schemas/CardHintTag' relation: $ref: '#/components/schemas/CardHintRelation' EpicBrief: type: object description: brief view of epic to be used in a card properties: id: type: string description: epic id example: e-123 title: type: string description: epic title example: Epic Title icon: $ref: '#/components/schemas/Image' ChecklistItem: type: object properties: id: type: string example: '4312' x-go-custom-tag: diff:"id,identifier" title: type: string example: Some title content: type: string example: Some description checklist_id: type: string example: '432' user_id: type: string example: u-du9saoj1 time_created: $ref: '#/components/schemas/STime' time_updated: $ref: '#/components/schemas/STime' checked: type: boolean example: true x-omitempty: false LinkedCardType: type: string enum: - blocks - blocked_by - related - duplicates example: blocks TagColor: type: string enum: - fog - slate - grey - charcoal - black - red - orange - yellow - green - ocean - blue - purple - pink example: blue nullable: true ExternalLinkType: type: string enum: - github_pull_request - generic GithubPullRequest: type: object properties: id: type: integer nullable: true number: type: integer nullable: true state: type: string nullable: true title: type: string nullable: true body: type: string nullable: true html_url: type: string nullable: true time_created: $ref: '#/components/schemas/STime' time_updated: $ref: '#/components/schemas/STime' time_closed: $ref: '#/components/schemas/STime' time_merged: $ref: '#/components/schemas/STime' head: $ref: '#/components/schemas/GithubPullRequestBranch' base: $ref: '#/components/schemas/GithubPullRequestBranch' draft: type: boolean nullable: true merged: type: boolean nullable: true GenericExternalLink: type: object required: - url properties: id: type: string description: Unique identifier for this external link (UUID) example: 550e8400-e29b-41d4-a716-446655440000 url: type: string display_text: type: string nullable: true time_added: $ref: '#/components/schemas/STime' CardHintTag: type: object properties: name: type: string enum: - bug - feature CardHintRelation: type: object properties: card: $ref: '#/components/schemas/HintCard' similarity: type: number format: float64 description: similarity score between 0 and 1 example: 0.8 GithubPullRequestBranch: type: object properties: label: type: string nullable: true ref: type: string nullable: true HintCard: type: object properties: title: type: string example: Create illustration for upcoming holidays card_id: type: string example: '42' x-go-custom-tag: diff:"card_id,identifier" user_id: type: string example: us4Fsfed project_id: type: string example: '3' board_id: type: string example: '15' board_title: type: string example: Ideas list_id: type: string example: '55' list_title: type: string example: Done list_color: type: string status: $ref: '#/components/schemas/CardStatus' securitySchemes: BearerAuth: type: http scheme: bearer ````