From fb4be1932b63f0dbb7fb29baf07ebefb8a88489c Mon Sep 17 00:00:00 2001 From: johnxie Date: Fri, 19 Jun 2026 03:56:30 -0700 Subject: [PATCH] docs(api): point readers at the live OpenAPI specs + webhook truth fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - developer-home: link the live v1/v2 OpenAPI specs as the source of truth, add an Errors section documenting the typed {ok,code,message} envelope (taskcade #26936) - webhooks: correct the stale 'no subscription endpoint' note — document the new POST /api/v2/subscribeWebhook + unsubscribeWebhook (Beta, Pro+), and make the Pro+ gating explicit (taskcade #26713) - llms.txt: surface the live v1/v2 specs + v2 reference + SDK + webhooks for LLM consumers - api-v2-reference: drop the hardcoded 'openapi 0.1.0' (the live spec owns the version) - retire the orphaned root 'Real API.json' (stale v1 snapshot, 42 paths vs 49 live; not referenced by any page — the embedded specs live under .gitbook/assets/) Handwritten reference pages kept as companion guides; the live spec is authoritative. Note: taskcade #26919 (90d /api login-JWT + refresh) needs no doc change — the public docs cover PAT + OAuth2 (both already accurate) and never document the legacy /api/login flow. --- Real API.json | 1 - .../api-v2-reference.md | 2 +- .../developer-home.md | 19 +++++++ apis-living-system-development/webhooks.md | 51 +++++++++++++++++-- llms.txt | 9 +++- 5 files changed, 75 insertions(+), 7 deletions(-) delete mode 100644 Real API.json diff --git a/Real API.json b/Real API.json deleted file mode 100644 index 0d2e530..0000000 --- a/Real API.json +++ /dev/null @@ -1 +0,0 @@ -{"openapi":"3.0.3","info":{"title":"Taskade Public API","description":"Taskade, the AI-Powered Productivity Platform.","version":"0.1.0"},"components":{"securitySchemes":{"oAuthAuthorizationCode":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://www.taskade.com/oauth2/authorize","tokenUrl":"https://www.taskade.com/oauth2/token","scopes":{}}}},"personalAccessToken":{"type":"http","scheme":"bearer"}},"schemas":{"Project":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the project. An alphanumeric string that is 16 characters long."},"name":{"type":"string","description":"The project’s name or title."}},"required":["id"],"additionalProperties":false},"ProjectShare":{"type":"object","properties":{"checkUrl":{"type":"string","format":"uri"},"editUrl":{"type":"string","format":"uri"},"viewUrl":{"type":"string","format":"uri"}},"required":["editUrl","viewUrl"],"additionalProperties":false,"description":"The share links of a project"},"ProjectTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id"],"additionalProperties":false},"Error":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusMessage":{"type":"string"}},"required":["ok","message","code","statusMessage"],"additionalProperties":false,"description":"Error description"},"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"parentId":{"type":"string","format":"uuid"},"completed":{"type":"boolean","default":false}},"required":["id"],"additionalProperties":false},"TaskNote":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"],"additionalProperties":false},"Date":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"ISO date format (YYYY-MM-DD), e.g. \"2021-12-31\""},"time":{"type":"string","pattern":"^(?:[0-1][0-9]|[2][0-3]):[0-5][0-9](?::[0-5][0-9])?$","nullable":true,"description":"Optional time component in 24-hour format (HH:MM:SS), e.g. \"15:30:45\". Can be null or omitted for date-only representations"},"timezone":{"type":"string","nullable":true,"description":"Optional timezone identifier (IANA timezone name), e.g. \"America/New_York\", \"Asia/Singapore\". Can be null or omitted for timezone-naive representations"}},"required":["date"],"additionalProperties":false},"SpaceAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"space_id":{"type":"string"},"data":{"type":"object","properties":{"commands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Human-readable name of the command in title case. This should probably be a verb."},"prompt":{"type":"string","minLength":1,"description":"Tell the agent what this command will do. It should be positioned as a direct instruction to the agent. At least 30 words."},"id":{"type":"string","minLength":1,"description":"ID based on the name in snake case."},"mode":{"type":"string","enum":["default","plan-and-execute-v1","plan-and-execute-v2"],"default":"default"}},"required":["name","prompt","id"],"additionalProperties":false}},"description":{"type":"string","description":"Role and purpose of agent, positioned as a direct instruction to the agent. Example: \"You are a doctor that helps save lives.\". At least 100 words."},"tone":{"type":"string","enum":["authoritative","clinical","cold","confident","cynical","emotional","empathetic","formal","friendly","humourous","informal","ironic","optimistic","pessimistic","playful","sarcastic","serious","sympathetic","tentative","warm","creative","inspiring","casual"]},"avatar":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["emoji"]},"data":{"type":"object","properties":{"value":{"type":"string","description":"Pick the most suitable emoji for this agent."}},"required":["value"],"additionalProperties":false}},"required":["type","data"],"additionalProperties":false}]},"knowledgeEnabled":{"type":"boolean"},"language":{"type":"string","description":"The language of the agent, e.g. en-US, zh-Hans"},"inputPlaceholder":{"type":"string"}},"required":["commands"],"additionalProperties":false}},"required":["id","name","space_id","data"],"additionalProperties":false},"Media":{"type":"object","properties":{"id":{"type":"string"},"space_id":{"type":"string"},"kind":{"type":"string"}},"required":["id","space_id","kind"],"additionalProperties":false},"User":{"type":"object","properties":{"handle":{"type":"string"},"displayName":{"type":"string"}},"required":["handle"],"additionalProperties":false},"Field":{"type":"object","properties":{"id":{"type":"string"},"data":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["boolean"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Note"]},"fillerConfig":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["string.translate"]},"sourceRef":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["field"]},"fieldPath":{"type":"string"}},"required":["type","fieldPath"],"additionalProperties":false}]},"targetLang":{"type":"string"}},"required":["type","sourceRef","targetLang"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["string.summarize"]},"sourceRef":{"$ref":"#/properties/data/anyOf/1/properties/fillerConfig/anyOf/0/properties/sourceRef"},"additionalInstructions":{"type":"string"}},"required":["type","sourceRef"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["string.extract"]},"sourceRef":{"$ref":"#/properties/data/anyOf/1/properties/fillerConfig/anyOf/0/properties/sourceRef"},"entity":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["email_address"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["first_name"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["last_name"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["phone_number"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["domain_name"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["link"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["date"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["time"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["year"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["custom"]},"instructions":{"type":"string"}},"required":["type","instructions"],"additionalProperties":false}]}},"required":["type","sourceRef","entity"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["string.custom"]},"instructions":{"type":"string"}},"required":["type","instructions"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Select.pick"]},"sourceRef":{"$ref":"#/properties/data/anyOf/1/properties/fillerConfig/anyOf/0/properties/sourceRef"},"permittedOptionIds":{"type":"array","items":{"type":"string"}},"additionalInstructions":{"type":"string"}},"required":["type","sourceRef","permittedOptionIds"],"additionalProperties":false}]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Timestamp"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["TimestampAt"]},"displayName":{"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["TimestampAuthor"]},"displayName":{"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"displayName":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["Select"]},"options":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rank":{"type":"string"},"description":{"type":"string"},"color":{"type":"string"}},"required":["id","name","rank"],"additionalProperties":false}},"defaultOption":{"type":"string"},"fillerConfig":{"$ref":"#/properties/data/anyOf/1/properties/fillerConfig"}},"required":["displayName","type","options"],"additionalProperties":false},{"type":"object","properties":{"displayName":{"type":"string","minLength":1},"type":{"type":"string","enum":["number"]},"render":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false}]},"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["decimal"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["currency"]},"config":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["standard"]},"code":{"type":"string","minLength":1}},"required":["type","code"],"additionalProperties":false}]}},"required":["type","config"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["unit"]},"config":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["standard"]},"unit":{"type":"string","minLength":1}},"required":["type","unit"],"additionalProperties":false}]}},"required":["type","config"],"additionalProperties":false}]}},"required":["displayName","type","render","format"],"additionalProperties":false},{"type":"object","properties":{"displayName":{"type":"string","minLength":1},"type":{"type":"string","enum":["string"]},"description":{"type":"string"},"fillerConfig":{"$ref":"#/properties/data/anyOf/1/properties/fillerConfig"}},"required":["displayName","type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Password"]},"title":{"type":"string"},"description":{"type":"string"},"hashAlgorithm":{"type":"string","enum":["bcrypt","argon2","scrypt","pbkdf2"],"default":"bcrypt"},"minLength":{"type":"integer","minimum":1,"default":8},"maxLength":{"type":"integer","minimum":1}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Assign"]},"title":{"type":"string"},"description":{"type":"string"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["DateTime"]},"title":{"type":"string"},"description":{"type":"string"},"format":{"type":"object","properties":{"time":{"type":"boolean"},"zone":{"anyOf":[{"type":"boolean"},{"type":"string"}]}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["DateRange"]},"title":{"type":"string"},"description":{"type":"string"},"format":{"type":"object","properties":{"time":{"type":"boolean"},"zone":{"anyOf":[{"type":"boolean"},{"type":"string"}]}},"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["NodeText"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["NodeCompleted"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["Unimplemented"]}},"required":["type"],"additionalProperties":false}]}},"required":["id","data"],"additionalProperties":false},"FieldValue":{"type":"object","properties":{"fieldId":{"type":"string"},"value":{}},"required":["fieldId"],"additionalProperties":false},"Block":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"completed":{"type":"boolean","default":false}},"required":["id"],"additionalProperties":false},"Convo":{"type":"object","properties":{"id":{"type":"string"},"space_agent_id":{"type":"string"},"status":{"type":"string","enum":["in_progress","idle","requires_review"]},"title":{"type":"string"},"data":{"type":"object","properties":{"llm":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["openai"]},"name":{"type":"string","enum":["gpt-3.5-turbo","gpt-4o","gpt-4-turbo","gpt-4o-mini","gpt-4.1","gpt-4.1-mini","gpt-4.1-nano","o3-mini:low","o3-mini:medium","o3-mini:high","o4-mini:low","o4-mini:medium","o4-mini:high","openai/gpt-4o","openai/gpt-4o-mini","openai/gpt-4.1","openai/gpt-4.1-mini","openai/gpt-4.1-nano","openai/gpt-5","openai/gpt-5:high","openai/gpt-5-mini","openai/gpt-5-mini:high","openai/gpt-5-nano","openai/gpt-5-nano:high","openai/gpt-5.1","openai/gpt-5.1:low","openai/gpt-5.1:medium","openai/gpt-5.1:high","openai/gpt-5.1-codex","openai/gpt-5.1-codex:low","openai/gpt-5.1-codex:medium","openai/gpt-5.1-codex:high"]}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["anthropic"]},"name":{"type":"string","enum":["anthropic/claude-3.5-sonnet","anthropic/claude-3.5-haiku","anthropic/claude-3.7-sonnet","anthropic/claude-4.0-sonnet","anthropic/claude-4.0-opus","anthropic/claude-sonnet-4.5","anthropic/claude-sonnet-4.5:thinking","anthropic/claude-haiku-4.5","anthropic/claude-haiku-4.5:thinking","anthropic/claude-opus-4.5","anthropic/claude-opus-4.5:thinking"]}},"required":["type","name"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["google"]},"name":{"type":"string","enum":["google/gemini-2.5-pro","google/gemini-2.5-flash","google/gemini-2.5-flash-lite","google/gemini-3-pro-preview"]}},"required":["type","name"],"additionalProperties":false}]},"endedAt":{"type":"number"}},"additionalProperties":false}},"required":["id","space_agent_id","status","data"],"additionalProperties":false}}},"paths":{"/workspaces/{workspaceId}/projects":{"post":{"operationId":"workspaceCreateProject","tags":["Workspace"],"description":"Create a project in a workspace","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","enum":["text/markdown"]},"content":{"type":"string"}},"required":["contentType","content"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Successful Project creation","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/Project"}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Project creation"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces":{"get":{"operationId":"workspacesGet","tags":["Workspace"],"description":"Get all workspaces for a user","responses":{"200":{"description":"Workspaces","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the workspace or folder. An alphanumeric string that is either 16 characters long or 9 characters long (the 9-character version may include underscores or hyphens)"},"name":{"type":"string","description":"Name of the workspace or folder."}},"required":["id","name"],"additionalProperties":false,"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Workspaces"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/workspaces/{workspaceId}/folders":{"get":{"operationId":"workspaceFoldersGet","tags":["Workspace"],"description":"Get all folders for a workspace","parameters":[{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Folders","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the workspace or folder. An alphanumeric string that is either 16 characters long or 9 characters long (the 9-character version may include underscores or hyphens)"},"name":{"type":"string","description":"Name of the workspace or folder."}},"required":["id","name"],"additionalProperties":false,"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Folders"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}":{"get":{"operationId":"projectGet","tags":["Project"],"description":"Get project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Project","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/Project"}},"required":["ok","item"],"additionalProperties":false,"description":"Project"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/complete":{"post":{"operationId":"projectComplete","tags":["Project"],"description":"Mark the project as completed","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Completed project","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Project"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Completed project"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/restore":{"post":{"operationId":"projectRestore","tags":["Project"],"description":"Restore project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Restored project","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Project"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Restored project"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/copy":{"post":{"operationId":"projectCopy","tags":["Project"],"description":"Copy a project to a folder","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"type":"string","minLength":1},"projectTitle":{"type":"string","minLength":1}},"required":["folderId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Successful Project Copied","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Project"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Project Copied"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"post":{"operationId":"projectCreate","tags":["Project"],"description":"Create a project in a team","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"type":"string","minLength":1},"contentType":{"type":"string","enum":["text/markdown"]},"content":{"type":"string"}},"required":["folderId","contentType","content"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Successful Project creation","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Project"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Project creation"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/from-template":{"post":{"operationId":"projectFromTemplate","tags":["Project"],"description":"Create a project from a custom template","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"type":"string","minLength":1},"templateId":{"type":"string","minLength":1}},"required":["folderId","templateId"],"additionalProperties":false}}},"required":true},"responses":{"200":{"description":"Successful Project creation from template","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Project"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Project creation from template"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/members":{"get":{"operationId":"projectMembersGet","tags":["Project"],"description":"Get members of a project","parameters":[{"schema":{"type":"number","default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Project members.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/User"}],"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Project members."}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/fields":{"get":{"operationId":"projectFieldsGet","tags":["Project"],"description":"Get all fields for a project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Project fields","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Field"}}},"required":["ok","items"],"additionalProperties":false,"description":"Project fields"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/shareLink":{"get":{"operationId":"projectShareLinkGet","tags":["Project"],"description":"Get share link for the project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Share link","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/ProjectShare"}],"nullable":true,"description":"The share links of a project"}},"required":["ok","item"],"additionalProperties":false,"description":"Share link"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"projectShareLinkEnable","tags":["Project"],"description":"Enable share link in the project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Share link successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/ProjectShare"}},"required":["ok","item"],"additionalProperties":false,"description":"Share link successfully created"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/blocks":{"get":{"operationId":"projectBlocksGet","tags":["Project"],"description":"Get all blocks for a project","parameters":[{"schema":{"type":"number","default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"after","required":false,"description":"Parameter for cursor-based pagination. Specify task ID to get blocks after it. Do not specify both before and after."},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"before","required":false,"description":"Parameter for cursor-based pagination. Specify task ID to get blocks before it. Do not specify both before and after."},{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Blocks","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Block"}}},"required":["ok","items"],"additionalProperties":false,"description":"Blocks"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks":{"get":{"operationId":"projectTasksGet","tags":["Project"],"description":"Get all tasks for a project","parameters":[{"schema":{"type":"number","default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"after","required":false,"description":"Parameter for cursor-based pagination. Specify task ID to get tasks after it. Do not specify both before and after."},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"before","required":false,"description":"Parameter for cursor-based pagination. Specify task ID to get tasks before it. Do not specify both before and after."},{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Tasks","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}},"required":["ok","items"],"additionalProperties":false,"description":"Tasks"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}":{"get":{"operationId":"taskGet","tags":["Task"],"description":"Get task with id","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Task"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"taskDelete","tags":["Task"],"description":"Delete a task in a project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful Task deletion","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false,"description":"Successful Task deletion"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"taskPut","tags":["Task"],"description":"Update task.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","enum":["text/markdown","text/plain"]},"content":{"type":"string","pattern":"^[^\\r\\n]*$","maxLength":2000}},"required":["contentType","content"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Updated task","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Updated task"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/complete":{"post":{"operationId":"taskComplete","tags":["Task"],"description":"Complete a task in a project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful complete a Task","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful complete a Task"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/uncomplete":{"post":{"operationId":"taskUncomplete","tags":["Task"],"description":"Mark a task as incomplete in a project","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful mark the Task as incomplete","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful mark the Task as incomplete"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/":{"post":{"operationId":"taskCreate","tags":["Task"],"description":"Create one or more tasks in a project","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"allOf":[{"type":"object","properties":{"contentType":{"type":"string","enum":["text/markdown","text/plain"]},"content":{"type":"string","maxLength":2000}},"required":["contentType","content"]},{"anyOf":[{"type":"object","properties":{"taskId":{"enum":["null"],"nullable":true},"placement":{"type":"string","enum":["afterbegin","beforeend"]}},"required":["placement"],"additionalProperties":false},{"type":"object","properties":{"taskId":{"type":"string"},"placement":{"type":"string","enum":["beforebegin","afterbegin","beforeend","afterend"]}},"required":["taskId","placement"],"additionalProperties":false}]}]},"maxItems":20}},"required":["tasks"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true,"description":"Unique identifier for the project."}],"responses":{"200":{"description":"Successful Tasks creation","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Tasks creation"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/move":{"put":{"operationId":"taskMove","tags":["Task"],"description":"Move a task within the project","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"object","properties":{"taskId":{"type":"string","minLength":1},"position":{"type":"string","enum":["beforebegin","afterbegin","beforeend","afterend"]}},"required":["taskId","position"],"additionalProperties":false}},"required":["target"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful move Task","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful move Task"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/assignees":{"get":{"operationId":"taskAssigneesGet","tags":["Task"],"description":"Get the assignees of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Task assignees","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/User"}}},"required":["ok","items"],"additionalProperties":false,"description":"Task assignees"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"taskPutAssignees","tags":["Task"],"description":"Task assignment","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"handles":{"type":"array","items":{"type":"string","minLength":1}}},"required":["handles"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful Task assignment","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Task assignment"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/assignees/{assigneeHandle}":{"delete":{"operationId":"taskDeleteAssignees","tags":["Task"],"description":"Remove assignee from a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true},{"schema":{"type":"string"},"in":"path","name":"assigneeHandle","required":true}],"responses":{"200":{"description":"Successful Task Assignment deletion","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Task Assignment deletion"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/date":{"get":{"operationId":"taskGetDate","tags":["Task"],"description":"Get the date of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Task Date","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/Date"},"end":{"anyOf":[{"$ref":"#/components/schemas/Date"},{"type":"object","properties":{"period":{"type":"string"}},"required":["period"],"additionalProperties":false}],"nullable":true}},"required":["start"],"additionalProperties":false}},"required":["ok","item"],"additionalProperties":false,"description":"Task Date"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"taskDeleteDate","tags":["Task"],"description":"Delete date of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful Task Date deletion","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Task Date deletion"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"taskPutDate","tags":["Task"],"description":"Create or update date for a task","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/Date"},"end":{"$ref":"#/components/schemas/Date"}},"required":["start"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful Task Date create or update","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Task"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Task Date create or update"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/note":{"get":{"operationId":"taskNoteGet","tags":["Task"],"description":"Get the note of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Task Note","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/TaskNote"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Task Note"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"taskNotePut","tags":["Task"],"description":"Add/update a note to the task","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["text/plain","text/markdown"]},"value":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"}},"required":["type","value"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful Task Note creation/update","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"allOf":[{"$ref":"#/components/schemas/TaskNote"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Successful Task Note creation/update"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"taskNoteDelete","tags":["Task"],"description":"Delete the note of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Successful Task Note deletion","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false,"description":"Successful Task Note deletion"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/fields":{"get":{"operationId":"taskFieldsValueGet","tags":["Task"],"description":"Get all field values for a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true}],"responses":{"200":{"description":"Task field values","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/FieldValue"}}},"required":["ok","items"],"additionalProperties":false,"description":"Task field values"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/tasks/{taskId}/fields/{fieldId}":{"get":{"operationId":"taskFieldValueGet","tags":["Task"],"description":"Get the field value of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true},{"schema":{"type":"string"},"in":"path","name":"fieldId","required":true}],"responses":{"200":{"description":"Task field value","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"$ref":"#/components/schemas/FieldValue"}},"required":["ok","item"],"additionalProperties":false,"description":"Task field value"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"taskFieldValueDelete","tags":["Task"],"description":"Delete the field value of a task","parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true},{"schema":{"type":"string"},"in":"path","name":"fieldId","required":true}],"responses":{"200":{"description":"Successful field value deletion","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false,"description":"Successful field value deletion"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"taskFieldValuePut","tags":["Task"],"description":"Update/create the field value of a task","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"anyOf":[{"type":"number"},{"type":"string","minLength":1}]}},"required":["value"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"projectId","required":true},{"schema":{"type":"string"},"in":"path","name":"taskId","required":true},{"schema":{"type":"string"},"in":"path","name":"fieldId","required":true}],"responses":{"200":{"description":"Successful field value create/update","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false,"description":"Successful field value create/update"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}/projects":{"get":{"operationId":"folderProjectsGet","tags":["Folder"],"description":"Get all projects in a team, or in the home team of a workspace.","parameters":[{"schema":{"type":"string"},"in":"path","name":"folderId","required":true,"description":"Folder/Workspace/Space ID"}],"responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Project"}],"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Projects"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}/agent-generate":{"post":{"operationId":"folderAgentGenerate","tags":["Folder"],"description":"Generate agent based on input text prompts","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"folderId","required":true}],"responses":{"200":{"description":"Default response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/SpaceAgent"}},"required":["ok","item"],"additionalProperties":false}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}/agents":{"post":{"operationId":"folderCreateAgent","tags":["Folder"],"description":"Create an agent in a team or workspace.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"data":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["data"]},"data":{"$ref":"#/components/schemas/SpaceAgent/properties/data"}},"required":["type","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["template"]},"template":{"type":"object","properties":{"type":{"type":"string","enum":["Tasker","Researcher","Marketer","EmailWriter","Sales","CustomerSupport","ProjectManager","ContentCreator","Copywriter","LegalAdvisor","SeoSpecialist","ProductivityCoach","EngineeringExpert","Translator","Summarizer","ResumeBuilder","Storyteller","Tutor","BrandStrategist","SocialMediaSpecialist","BusinessStrategist","FinancialAnalyst","HumanResourcesManager","DataScientist","ITConsultant","FinancialAdvisor","HealthCoach","SustainabilityConsultant","UXDesigner","QualityAssuranceAnalyst","ProductManager","GrowthHacker","BusinessDevelopmentManager","PublicRelationsSpecialist","EventPlanner","DataAnalyst","Editor","CEO","InterviewCoach","TechSupportAdvisor","Doctor","BlogExpert","TweetOptimizer","EmailMarketer","CourseCreator","ScriptCreator","ScreenplayWriter","Proofreader","SalesColdEmailCoach","CodeExplainer","CreativeWritingCoach","AdvertisingCopywriter","VideoScriptWriter","ProjectArchitect","AICouncil","Negotiator","VCAssociate","Books","StartupMentor","SmallBusiness","WebDevelopment","PromptEngineer","ArticleWriter","WorkflowAgent","StrategyAgent","ViralAgent","SOPOnboardingAgent","PressReleaseAgent"]},"avatar":{"$ref":"#/components/schemas/SpaceAgent/properties/data/properties/avatar"}},"required":["type"],"additionalProperties":false}},"required":["type","template"],"additionalProperties":false}]}},"required":["name","data"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"folderId","required":true}],"responses":{"200":{"description":"Default response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/SpaceAgent"}},"required":["ok","item"],"additionalProperties":false}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"folderAgentGet","tags":["Folder"],"description":"Get agents in a folder.","parameters":[{"schema":{"type":"number","default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"path","name":"folderId","required":true}],"responses":{"200":{"description":"Agents","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SpaceAgent"}],"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Agents"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}/medias":{"get":{"operationId":"mediasGet","tags":["Folder"],"description":"Get medias in a folder","parameters":[{"schema":{"type":"number","default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"path","name":"folderId","required":true}],"responses":{"200":{"description":"Medias","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Media"}],"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Medias"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}/project-templates":{"get":{"operationId":"folderProjectTemplatesGet","tags":["Folder"],"description":"Get projects templates in a folder.","parameters":[{"schema":{"type":"number","default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"path","name":"folderId","required":true}],"responses":{"200":{"description":"Project Templates","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ProjectTemplate"}],"nullable":true}}},"required":["ok","items"],"additionalProperties":false,"description":"Project Templates"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/projects":{"get":{"operationId":"meProjectsGet","tags":["Me"],"description":"Get all projects of mine","parameters":[{"schema":{"type":"number","default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"string","enum":["viewed-asc","viewed-desc"],"default":"viewed-desc"},"in":"query","name":"sort","required":false}],"responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["ok","items"],"additionalProperties":false,"description":"Projects"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/publicAccess":{"put":{"operationId":"agentPublicAccessEnable","tags":["Agent"],"description":"Enable public access in the agent","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Public access successfully enabled","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"publicUrl":{"type":"string","format":"uri"}},"required":["ok","publicUrl"],"additionalProperties":false,"description":"Public access successfully enabled"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}":{"get":{"operationId":"agentGet","tags":["Agent"],"description":"Get agent with id","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/SpaceAgent"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Agent"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAgent","tags":["Agent"],"description":"Delete an agent","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Agent successfully deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false,"description":"Agent successfully deleted"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"agentUpdate","tags":["Agent"],"description":"Update agent","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"data":{"$ref":"#/components/schemas/SpaceAgent/properties/data"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Agent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/SpaceAgent"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Agent"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/public-agent":{"get":{"operationId":"agentPublicGet","tags":["Agent"],"description":"Get public agent","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Public Agent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"data":{"type":"object","properties":{"avatar":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["custom"]},"data":{"type":"object","properties":{"file":{"type":"object","properties":{"ownerID":{"type":"string"},"ownerType":{"type":"string","minLength":1,"nullable":true},"id":{"type":"string"},"namespace":{"type":"string"},"extension":{"type":"string"},"s3KeyOriginal":{"type":"string"},"userID":{"type":"number","nullable":true},"spaceID":{"type":"string","minLength":1,"nullable":true},"documentID":{"type":"string","minLength":1,"nullable":true},"nodeID":{"type":"string","minLength":1,"nullable":true},"size":{"type":"number"},"mimetype":{"type":"string"},"metadata":{"type":"object","properties":{},"additionalProperties":true},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["ownerID","id","namespace","extension","s3KeyOriginal","size","mimetype"],"additionalProperties":true}},"required":["file"],"additionalProperties":false}},"required":["type","data"],"additionalProperties":false},{"$ref":"#/components/schemas/SpaceAgent/properties/data/properties/avatar/anyOf/0"}]},"conversationStarters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"text":{"type":"string","minLength":1},"prompt":{"type":"string"}},"required":["id","text"],"additionalProperties":false}}},"additionalProperties":false},"preferences":{"type":"object","properties":{"mode":{"type":"string","enum":["template","chatbot"]},"canCopyKnowledge":{"type":"boolean"},"hideBranding":{"type":"boolean"},"theme":{"type":"string","enum":["light","dark","auto"]},"autoEndChats":{"type":"boolean"},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"image":{"allOf":[{"$ref":"#/properties/item/properties/data/properties/avatar/anyOf/0/properties/data/properties/file"}],"nullable":true}},"additionalProperties":false}},"additionalProperties":false}},"required":["id","name","data","preferences"],"additionalProperties":false},"publicUrl":{"type":"string","format":"uri"}},"required":["ok","item","publicUrl"],"additionalProperties":false,"description":"Public Agent"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"agentPublicUpdate","tags":["Agent"],"description":"Update public agent","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","properties":{"mode":{"type":"string","enum":["template","chatbot"]},"canCopyKnowledge":{"type":"boolean"},"hideBranding":{"type":"boolean"},"theme":{"type":"string","enum":["light","dark","auto"]},"autoEndChats":{"type":"boolean"},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"image":{"type":"object","properties":{"ownerID":{"type":"string"},"ownerType":{"type":"string","minLength":1,"nullable":true},"id":{"type":"string"},"namespace":{"type":"string"},"extension":{"type":"string"},"s3KeyOriginal":{"type":"string"},"userID":{"type":"number","nullable":true},"spaceID":{"type":"string","minLength":1,"nullable":true},"documentID":{"type":"string","minLength":1,"nullable":true},"nodeID":{"type":"string","minLength":1,"nullable":true},"size":{"type":"number"},"mimetype":{"type":"string"},"metadata":{"type":"object","properties":{},"additionalProperties":true},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["ownerID","id","namespace","extension","s3KeyOriginal","size","mimetype"],"additionalProperties":true,"nullable":true}},"additionalProperties":false}},"additionalProperties":false}},"required":["preferences"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Public Agent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"data":{"type":"object","properties":{"avatar":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["custom"]},"data":{"type":"object","properties":{"file":{"type":"object","properties":{"ownerID":{"type":"string"},"ownerType":{"type":"string","minLength":1,"nullable":true},"id":{"type":"string"},"namespace":{"type":"string"},"extension":{"type":"string"},"s3KeyOriginal":{"type":"string"},"userID":{"type":"number","nullable":true},"spaceID":{"type":"string","minLength":1,"nullable":true},"documentID":{"type":"string","minLength":1,"nullable":true},"nodeID":{"type":"string","minLength":1,"nullable":true},"size":{"type":"number"},"mimetype":{"type":"string"},"metadata":{"type":"object","properties":{},"additionalProperties":true},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["ownerID","id","namespace","extension","s3KeyOriginal","size","mimetype"],"additionalProperties":true}},"required":["file"],"additionalProperties":false}},"required":["type","data"],"additionalProperties":false},{"$ref":"#/components/schemas/SpaceAgent/properties/data/properties/avatar/anyOf/0"}]},"conversationStarters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"text":{"type":"string","minLength":1},"prompt":{"type":"string"}},"required":["id","text"],"additionalProperties":false}}},"additionalProperties":false},"preferences":{"type":"object","properties":{"mode":{"type":"string","enum":["template","chatbot"]},"canCopyKnowledge":{"type":"boolean"},"hideBranding":{"type":"boolean"},"theme":{"type":"string","enum":["light","dark","auto"]},"autoEndChats":{"type":"boolean"},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"image":{"allOf":[{"$ref":"#/properties/item/properties/data/properties/avatar/anyOf/0/properties/data/properties/file"}],"nullable":true}},"additionalProperties":false}},"additionalProperties":false}},"required":["id","name","data","preferences"],"additionalProperties":false}},"required":["ok","item"],"additionalProperties":false,"description":"Public Agent"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/knowledge/project":{"post":{"operationId":"agentKnowledgeProjectCreate","tags":["Agent"],"description":"Create a knowledge project","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string"}},"required":["projectId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Project knowledge created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/SpaceAgent"}},"required":["ok","item"],"additionalProperties":false,"description":"Project knowledge created"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/knowledge/media":{"post":{"operationId":"agentKnowledgeMediaCreate","tags":["Agent"],"description":"Create a knowledge media","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"type":"string"}},"required":["mediaId"],"additionalProperties":false}}},"required":true},"parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Media knowledge created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/SpaceAgent"}},"required":["ok","item"],"additionalProperties":false,"description":"Media knowledge created"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/knowledge/project/{projectId}":{"delete":{"operationId":"agentKnowledgeProjectRemove","tags":["Agent"],"description":"Remove a knowledge project","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"projectId","required":true}],"responses":{"200":{"description":"Project knowledge removed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false,"description":"Project knowledge removed"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/knowledge/media/{mediaId}":{"delete":{"operationId":"agentKnowledgeMediaRemove","tags":["Agent"],"description":"Remove a knowledge media","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"mediaId","required":true}],"responses":{"200":{"description":"Media knowledge removed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false,"description":"Media knowledge removed"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/convos/":{"get":{"operationId":"agentConvosGet","tags":["Agent"],"description":"Get agent conversations","parameters":[{"schema":{"type":"number","default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"number","default":1},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"path","name":"agentId","required":true}],"responses":{"200":{"description":"Agent conversations","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Convo"}}},"required":["ok","items"],"additionalProperties":false,"description":"Agent conversations"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/{agentId}/convos/{convoId}":{"get":{"operationId":"agentConvoGet","tags":["Agent"],"description":"Get agent conversation by id","parameters":[{"schema":{"type":"string"},"in":"path","name":"agentId","required":true},{"schema":{"type":"string"},"in":"path","name":"convoId","required":true}],"responses":{"200":{"description":"Agent conversation","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"$ref":"#/components/schemas/Convo"}},"required":["ok","item"],"additionalProperties":false,"description":"Agent conversation"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/medias/{mediaId}":{"get":{"operationId":"mediaGet","tags":["Media"],"description":"Get media with id","parameters":[{"schema":{"type":"string"},"in":"path","name":"mediaId","required":true}],"responses":{"200":{"description":"Media","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"allOf":[{"$ref":"#/components/schemas/Media"}],"nullable":true}},"required":["ok","item"],"additionalProperties":false,"description":"Media"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"mediaDelete","tags":["Media"],"description":"Delete a media","parameters":[{"schema":{"type":"string"},"in":"path","name":"mediaId","required":true}],"responses":{"200":{"description":"Successful Media deletion","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"],"additionalProperties":false,"description":"Successful Media deletion"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public-agents/{publicAgentId}":{"get":{"operationId":"publicAgentGet","tags":["Agent"],"description":"Get public agent by public agent ID","parameters":[{"schema":{"type":"string"},"in":"path","name":"publicAgentId","required":true}],"responses":{"200":{"description":"Public Agent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"item":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"data":{"type":"object","properties":{"avatar":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["custom"]},"data":{"type":"object","properties":{"file":{"type":"object","properties":{"ownerID":{"type":"string"},"ownerType":{"type":"string","minLength":1,"nullable":true},"id":{"type":"string"},"namespace":{"type":"string"},"extension":{"type":"string"},"s3KeyOriginal":{"type":"string"},"userID":{"type":"number","nullable":true},"spaceID":{"type":"string","minLength":1,"nullable":true},"documentID":{"type":"string","minLength":1,"nullable":true},"nodeID":{"type":"string","minLength":1,"nullable":true},"size":{"type":"number"},"mimetype":{"type":"string"},"metadata":{"type":"object","properties":{},"additionalProperties":true},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"required":["ownerID","id","namespace","extension","s3KeyOriginal","size","mimetype"],"additionalProperties":true}},"required":["file"],"additionalProperties":false}},"required":["type","data"],"additionalProperties":false},{"$ref":"#/components/schemas/SpaceAgent/properties/data/properties/avatar/anyOf/0"}]},"conversationStarters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"text":{"type":"string","minLength":1},"prompt":{"type":"string"}},"required":["id","text"],"additionalProperties":false}}},"additionalProperties":false},"preferences":{"type":"object","properties":{"mode":{"type":"string","enum":["template","chatbot"]},"canCopyKnowledge":{"type":"boolean"},"hideBranding":{"type":"boolean"},"theme":{"type":"string","enum":["light","dark","auto"]},"autoEndChats":{"type":"boolean"},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"image":{"allOf":[{"$ref":"#/properties/item/properties/data/properties/avatar/anyOf/0/properties/data/properties/file"}],"nullable":true}},"additionalProperties":false}},"additionalProperties":false}},"required":["id","name","data","preferences"],"additionalProperties":false},"publicUrl":{"type":"string","format":"uri"}},"required":["ok","item","publicUrl"],"additionalProperties":false,"description":"Public Agent"}}}},"4XX":{"description":"Error description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"servers":[{"url":"https://www.taskade.com/api/v1","description":"Public API server"}],"security":[{"oAuthAuthorizationCode":[],"personalAccessToken":[]}]} \ No newline at end of file diff --git a/apis-living-system-development/api-v2-reference.md b/apis-living-system-development/api-v2-reference.md index 8286803..5d6f6c5 100644 --- a/apis-living-system-development/api-v2-reference.md +++ b/apis-living-system-development/api-v2-reference.md @@ -9,7 +9,7 @@ description: >- The Public API **v2** is an **action-based** API: every operation is a `POST` to a named endpoint (`/listSpaces`, `/promptAgent`, `/createProject`), with a JSON body. It is not RESTful — there are no `GET /workspaces` or `PUT /tasks/{id}` style routes. {% hint style="info" %} -**v2 is in beta and runs alongside v1.** v2 (`openapi 0.1.0`) is simpler and adds capabilities v1 lacks — most notably **`promptAgent`**. But v2 does **not** cover everything: tasks are **read-only** in v2, and there is no project-update endpoint. For full task CRUD (create/update/delete, assignees, dates, notes, fields) use the [REST API v1](comprehensive-api-guide/). See [Which API should I use?](#which-api-should-i-use) below. +**v2 is in beta and runs alongside v1.** v2 is simpler and adds capabilities v1 lacks — most notably **`promptAgent`**. But v2 does **not** cover everything: tasks are **read-only** in v2, and there is no project-update endpoint. For full task CRUD (create/update/delete, assignees, dates, notes, fields) use the [REST API v1](comprehensive-api-guide/). See [Which API should I use?](#which-api-should-i-use) below. {% endhint %} The live OpenAPI spec is published at [taskade.com/api/documentation/v2](https://www.taskade.com/api/documentation/v2). diff --git a/apis-living-system-development/developer-home.md b/apis-living-system-development/developer-home.md index 8a0c0cc..ebe0df2 100644 --- a/apis-living-system-development/developer-home.md +++ b/apis-living-system-development/developer-home.md @@ -109,6 +109,15 @@ Taskade ships **two** public HTTP APIs, both authenticated with the same token: | [REST API v1](comprehensive-api-guide/README.md) | `https://www.taskade.com/api/v1` | RESTful (`GET`/`POST`/`PUT`/`DELETE`) | Full task CRUD, assignees, dates, notes, fields | | [Action API v2](api-v2-reference.md) | `https://www.taskade.com/api/v2` | Action / RPC (`POST /{operation}`) | Prompting agents, agent lifecycle, bundles | +{% hint style="info" %} +**Live OpenAPI specs (source of truth)** — auto-generated from the running API, always current: + +* REST API v1 — [interactive docs](https://www.taskade.com/api/documentation/v1) · [openapi.json](https://www.taskade.com/api/documentation/v1/json) +* Action API v2 — [interactive docs](https://www.taskade.com/api/documentation/v2) · [openapi.json](https://www.taskade.com/api/documentation/v2/json) + +The reference pages in this guide are hand-written companions (examples, patterns, best practices). When in doubt about an exact field or status code, the live spec wins. +{% endhint %} + Include your token in the `Authorization` header: ```bash @@ -122,6 +131,16 @@ curl -X POST https://www.taskade.com/api/v2/listMyProjects \ -H "Content-Type: application/json" -d '{}' ``` +## Errors + +Both APIs return a consistent JSON error envelope — expected failures come back as typed errors, not bare `500`s: + +```json +{ "ok": false, "code": "PAYMENT_REQUIRED", "message": "Webhooks require a Pro plan or higher." } +``` + +The HTTP status matches the `code` (e.g. `401` `UNAUTHORIZED`, `402` `PAYMENT_REQUIRED`, `403` `FORBIDDEN`, `404` `NOT_FOUND`, `429` `TOO_MANY_REQUESTS`). Branch on `ok` and `code` rather than parsing `message`. + ## What You Can Build - **Custom dashboards** that pull data from Taskade workspaces and projects diff --git a/apis-living-system-development/webhooks.md b/apis-living-system-development/webhooks.md index bf00707..7de3cdd 100644 --- a/apis-living-system-development/webhooks.md +++ b/apis-living-system-development/webhooks.md @@ -14,8 +14,11 @@ Webhooks let your Taskade automations communicate with the outside world in both * **Outbound HTTP requests** — automations call _out_ to external APIs as action steps. * **Receiving Taskade events** — combine a Taskade **trigger** (e.g. _task completed_) with an outbound HTTP action to push events to your app. -{% hint style="warning" %} -There is **no** `POST /api/v2/webhooks` subscription endpoint and no event-subscription REST API. You receive Taskade events by **building an automation** with a Taskade trigger plus an HTTP action — see [Receiving Taskade Events](#receiving-taskade-events) below. +{% hint style="info" %} +Two ways to receive Taskade events: + +* **No-code:** build an automation with a Taskade trigger plus an HTTP action — see [Receiving Taskade Events](#receiving-taskade-events) below. +* **Programmatic (Beta):** subscribe over the public API with `POST /api/v2/subscribeWebhook` — see [Programmatic Webhook Subscriptions](#programmatic-webhook-subscriptions-beta). Available on **Pro and above**. {% endhint %} *** @@ -91,7 +94,7 @@ Content-Type: application/json Requests that omit or supply an incorrect token receive a `401 Unauthorized` response and are not processed. {% hint style="info" %} -Check your plan's feature list at [taskade.com/pricing](https://www.taskade.com/pricing) for current availability of inbound webhook bearer token authentication. +Webhook automations are available on **Pro and above**. Free and Starter plans cannot create webhook triggers or subscriptions. See [taskade.com/pricing](https://www.taskade.com/pricing). {% endhint %} ### Common Patterns @@ -141,6 +144,48 @@ Response data from the HTTP request is available as dynamic variables in subsequ *** +## Programmatic Webhook Subscriptions (Beta) + +{% hint style="info" %} +Beta. Subscribing requires **Pro or above**. Subscriptions are account-level, and `task.due` is the only event wired end-to-end today — more events are rolling out. The authoritative schema is the live [Action API v2 spec](https://www.taskade.com/api/documentation/v2). +{% endhint %} + +Subscribe to Taskade events over the public API without building an automation in the UI. This is the surface the official [Taskade integrations](https://github.com/taskade/integrations) (Zapier, n8n, Activepieces) build on. + +**Subscribe** — register a target URL for an event: + +```http +POST https://www.taskade.com/api/v2/subscribeWebhook +Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN +Content-Type: application/json + +{ + "targetUrl": "https://your-app.example.com/hooks/taskade", + "triggerType": "task.due" +} +``` + +Returns `{ "ok": true, "hookId": "..." }`. Taskade then POSTs the event payload to `targetUrl` whenever a matching event fires. Delivery uses an SSRF-guarded fetch, so `targetUrl` **must be `https`**. + +**Unsubscribe** — remove a subscription by its `hookId`: + +```http +POST https://www.taskade.com/api/v2/unsubscribeWebhook +Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN +Content-Type: application/json + +{ "hookId": "..." } +``` + +| Note | Detail | +| --- | --- | +| Plan | Subscribing requires **Pro or above** (otherwise `402 PAYMENT_REQUIRED`). Unsubscribing is always allowed, so a downgraded account can still clean up. | +| Scope | Account-level — fires for matching events across your account. Per-project scope is planned. | +| Events | `task.due` today. `task.assigned`, `task.completed`, `project.created` and more are rolling out. | +| Limit | Up to 100 active subscriptions per account. | + +*** + ## Receiving Taskade Events To notify your app when something happens **in** Taskade (a task is added, a task is completed), build an automation that starts with a Taskade **trigger** and ends with an [Outbound HTTP Request](#outbound-http-requests) to your endpoint. The trigger's fields are available as dynamic variables in the HTTP body. diff --git a/llms.txt b/llms.txt index fed0750..039ef0d 100644 --- a/llms.txt +++ b/llms.txt @@ -52,10 +52,15 @@ Taskade lets teams collaborate on projects, create AI agents, automate workflows - [Developer Overview](apis-living-system-development/developers/README.md) - [Authentication](apis-living-system-development/developers/authentication.md) - [API Overview](apis-living-system-development/developers/api.md) -- [Comprehensive API Guide](apis-living-system-development/comprehensive-api-guide/README.md) +- [Comprehensive API Guide (REST v1)](apis-living-system-development/comprehensive-api-guide/README.md) +- [Action API v2 Reference (Beta)](apis-living-system-development/api-v2-reference.md) +- [TypeScript SDK Quickstart](apis-living-system-development/sdk-quickstart.md) +- [Webhooks](apis-living-system-development/webhooks.md) +- REST API v1 — live OpenAPI spec: https://www.taskade.com/api/documentation/v1 (JSON: https://www.taskade.com/api/documentation/v1/json) +- Action API v2 (Beta) — live OpenAPI spec: https://www.taskade.com/api/documentation/v2 (JSON: https://www.taskade.com/api/documentation/v2/json) ## Links - [Taskade Website](https://taskade.com) - [Taskade Blog](https://www.taskade.com/blog) -- [Taskade API](https://www.taskade.com/api/v1) +- [Taskade API docs](https://www.taskade.com/api/documentation/v2)