{ "openapi": "3.1.0", "info": { "title": "Nifty v3 API (Public)", "version": "0.132.0", "description": "The Nifty v3 REST API. Everything below is a cross-cutting rule that holds on every\nendpoint; the per-endpoint pages describe only what is specific to them.\n\n## Authentication\n\nSend a personal access token (`nft_user_…`) or an OAuth 2.1 access token (`nft_oauth_…`) as a bearer token on every request. There is no other\nauthentication method, no API key query parameter and no cookie fallback. A missing or\nexpired token answers **401**; a valid token that lacks the scope an endpoint needs answers\n**403** — each endpoint lists its required scopes under Security. Tokens are workspace-scoped:\none token reaches exactly one workspace.\n\n```http\nAuthorization: Bearer $NIFTY_TOKEN\n```\n\n## Base URL and versions\n\nEvery endpoint lives under `https://openapi.niftypm.com/api/v3`. Paths shown in this reference are relative to that\nbase. New fields and new endpoints can appear within v3 without notice —\nignore response keys you do not recognise rather than rejecting them.\n\nSee the [Getting started guide](https://developers.niftypm.com/docs/getting-started) for a first request end to end.\n\n```bash\ncurl https://openapi.niftypm.com/api/v3/tasks \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"\n```\n\n## Renamed names\n\nSome names have changed, so that one concept has one name everywhere. This reference publishes\nonly the current spelling; the retired spelling keeps working, so nothing breaks on the day a\nname changes.\n\nA call that uses a retired ROUTE spelling is answered normally and additionally carries\n`Deprecation: true` and a `Link` header naming the route that replaces it. A retired FIELD name\nsent in a standard create or update body is accepted and applied to the current field. Both are\naccepted but not published: read the current names here, and treat the headers as your list of\nwhat to change.\n\nThe exception is an operation with a purpose-built body — the request shape published on that\nendpoint is validated exactly, so send the names it lists rather than the ones a general create\ntakes.\n\nThere is no `Sunset` header and no removal date. Retired names go away in a later release,\nannounced in the changelog before it ships; until then they keep working, and we would rather\ngive no date than one we later have to move.\n\n```http\nHTTP/1.1 200 OK\nDeprecation: true\nLink: <../check-ins>; rel=\"successor-version\",\n ; rel=\"deprecation\"\n```\n\n## Pagination\n\nEvery collection returns the same envelope: `data` (the page), `total`, `limit`, `hasMore` and\n`nextCursor`. Page forward by passing the previous `nextCursor` back as `?cursor=` until\n`hasMore` is false — never by counting rows. `limit` accepts 1–200 and defaults to 50; a larger\nvalue is silently clamped to 200 rather than rejected, so a short page never means the end.\n`total` is computed only when you ask for it with `?includeTotal=true`, because counting matching\nrows costs an extra query.\n\n```json\n{ \"data\": [], \"total\": 42, \"limit\": 50, \"hasMore\": true, \"nextCursor\": \"b2NjdXJyZWRBdD0y\" }\n```\n\n## Expanding objects\n\nRelated objects are returned as ids by default. Pass `?expand=` with a comma-separated list to\ninline them, using a dot for a nested hop; paths may be up to four hops deep. Each read endpoint\npublishes the relations it can resolve as an enum on its own `expand` parameter — a relation\noutside that list is refused with **400** `expand_unknown_relation`, whose `available` array names\nthe legal ones. Expansion is never automatic: omit the parameter and you get ids only.\n\n```http\nGET /tasks?expand=assignees,project.owner\n```\n\n## Idempotent requests\n\nAny mutating request may carry an `Idempotency-Key` header of up to 250 characters. A retry\nsending the same key replays the FIRST call’s stored response instead of performing the work a\nsecond time, so a client that times out can retry safely. The key is remembered for **10 minutes**\nand is bound to the request body: reusing it with a different body is refused with **422** rather\nthan silently replaying the wrong result. Generate a fresh key per distinct request.\n\n```http\nIdempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\n```\n\n## Concurrency\n\nUpdates are last-writer-wins unless you say otherwise. To make an update conditional on the row\nnot having changed since you read it, send the `updatedAt` you read back as `expectedUpdatedAt` in\nthe request body. If another writer — a teammate, an agent or an automation — committed in the\nmeantime, the update is refused with **409** `stale_write`. Recover by re-reading the row,\nre-deriving your change from the current values, and retrying with the fresh `updatedAt`.\n\n```json\n{ \"name\": \"Ship the beta\", \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\" }\n```\n\n## Errors\n\nEvery failure returns the same RFC 7807 Problem Details body, served as `application/json`:\n`type`, `title`, `status` and `detail`, plus the Nifty extensions `code`, `requestId` and\n`docsUrl`. Branch on `code`, never on the wording of `detail`. A **400** from validation adds an\n`errors` array naming the offending fields. Quote `requestId` when you contact support — it\nidentifies the exact request in our logs.\n\nFull list with recovery steps: [Error reference](https://developers.niftypm.com/docs/errors).\n\n```json\n{ \"type\": \"resource_not_found\", \"title\": \"Resource not found\", \"status\": 404,\n \"detail\": \"task 'KfS0ha8P' not found or inaccessible\", \"code\": \"resource_not_found\",\n \"docsUrl\": \"https://developers.niftypm.com/docs/errors#resource_not_found\" }\n```\n\n## Rate limits\n\nLimits are per token and per HTTP method: 3,000 GETs per 5 minutes, 500 POSTs per minute,\n100 PATCHes per minute and 200 DELETEs per 10 minutes. Two buckets apply to each request, one\nkeyed by token and one by IP.\n\nBlock periods, and the status each limiter answers with: [Rate limits](https://developers.niftypm.com/docs/rate-limits).\n\n## Ids and timestamps\n\nResource ids are short opaque strings — treat them as text, never parse, pad or generate them,\nand never assume a length (today they run 8–17 characters, and that is not part of the contract).\nActor ids (`createdByActorId`, `updatedByActorId`) are UUIDs instead, because they identify a\nprincipal rather than a row, and the two id spaces are not interchangeable. Every timestamp is ISO\n8601 in UTC with millisecond precision, on both the way in and the way out. Fields ending in `Date`\nare calendar dates the workspace timezone applies to; fields ending in `At` are exact instants.\n\n```json\n{ \"id\": \"KfS0ha8P\", \"createdByActorId\": \"49f861f7-4af8-44bf-844f-45f85babe504\",\n \"createdAt\": \"2026-05-31T12:00:00.000Z\" }\n```\n\n## Soft delete and restore\n\nDELETE means two different things here, and each endpoint says which one it does. On a\nsoft-deleting resource the row moves to trash: it leaves list results at once, is purged\npermanently after a **30-day** retention window, and can be brought back before then with a\nrestore call such as `POST /documents/{id}/restore`. Everything else is destroyed immediately and\ncannot be recovered.\nRestoring something that is already active succeeds and changes nothing.\n\n```http\nPOST /tasks/KfS0ha8P/restore\n```", "contact": { "name": "Nifty Support", "email": "team@niftypm.com", "url": "https://help.niftypm.com/en/articles/6749505-nifty-api" } }, "servers": [ { "url": "https://openapi.niftypm.com/api/v3", "description": "Nifty v3 public API (the /api/v3 proxy)" } ], "externalDocs": { "description": "Nifty Help Center", "url": "https://help.niftypm.com/en/" }, "tags": [ { "name": "actor", "x-displayName": "Actor", "description": "Identity records for everyone and everything that writes to your workspace. Most resources return the id of the actor that created and last updated them; look that id up here to get a display name and to tell a person apart from an agent or an automated process. Actor ids are UUIDs, unlike the short ids used everywhere else in this API. This surface is read-only." }, { "name": "annotation", "x-displayName": "Annotation", "description": "A drawing or comment-anchor placed on a file — a shape on an image, or a moment in a video. Create places the anchor; commenting on it is a separate message (`POST /messages` with `annotationId`), and the first comment is what creates the annotation's comment thread. Read the thread with `?expand=messages`." }, { "name": "chat", "x-displayName": "Chat", "description": "A team-scoped conversation: a group chat, a direct message between two people, or a project's general discussion. Only group chats can be created here — a direct message is created for you when you post a message with `recipientMemberId`, and a project discussion is provisioned with its project. Members are set when the chat is created (`memberIds`) and cannot be changed afterwards. Messages live on the separate message resource — list them with `GET /messages?chatId=...`." }, { "name": "checkIn", "x-displayName": "Check-in", "description": "A team-scoped recurring or ad-hoc check-in attached to a form. Collects responses from assignees on a schedule (RecurringRule) or on demand. Notify types control how assignees are reminded (email, in-app message, push notification). Assignees and subscribers are managed one at a time through the `assignees` and `subscribers` sub-resource routes." }, { "name": "checkInRequest", "x-displayName": "Check-in request", "description": "One scheduled or manually triggered occurrence of a CheckIn. Each request fans out to its assignees so they can submit a FormResponse against the parent check-in form. Belongs to a CheckIn (which belongs to a Team). Assignees and respondedBy are managed one at a time through their sub-resource routes." }, { "name": "checklist", "x-displayName": "Checklist", "description": "A named, ordered container of checklist items on a task. Create requires taskId (immutable after create). Items live on the separate checklistItem resource (`?expand=checklistItems` to materialize them inline). Deleting a checklist deletes its items." }, { "name": "checklistItem", "x-displayName": "Checklist Item", "description": "A single completable line inside a checklist. Create requires checklistId (immutable after create). Toggle `completed` via update. Find legal checklistIds via the checklist resource (or task ?expand=checklists)." }, { "name": "customField", "x-displayName": "Custom Field", "description": "The definitions of a workspace's custom fields — their names, kinds and dropdown options.\n\nDefinitions themselves are managed in the Nifty app; this API exposes them read-only. What you do here is look up a definition so you can SET a value on something: include `customFields: [{ customFieldId, value }]` in a task, project, list or member create or update body.\n\n`value` is ALWAYS a string, whatever the field kind — send `\"true\"` or `\"false\"` for a `checkbox`, a member id for a `user` field, one of the option values from `?expand=options` for a `dropdown`, and the written-out value for the rest. Send `\"\"` to clear a field." }, { "name": "document", "x-displayName": "Document", "description": "A rich-text document that lives in a project. Create seeds the body from Markdown (`content`); after that the body can only be extended with the `append` operation, never replaced, and it is not returned by list or get — read it with the `content` operation. `accessType` CANNOT BE CHANGED after creation: choose it when you create the document, or change it in the Nifty app. Choosing `limited` also decides who can reach the document — the member list is seeded from the resolved author, so a document created by an agent is reachable by that author, not by the agent that called the API. A child document always inherits its parent's access type. Google- and Microsoft-linked documents are readable here but are created in those apps." }, { "name": "favorite", "x-displayName": "Favorite", "description": "One pinned item in the caller's own sidebar. You only ever see, create and delete your own.\n\n`type` decides what `resourceId` points at, and two of the types also need a `projectId`:\n\n| `type` | `resourceId` | `projectId` |\n| --- | --- | --- |\n| `project`, `projectEmbed` | required | required |\n| `document`, `file`, `fileFolder`, `documentFolder` | required | — |\n| `personalNotes`, `personalTasks`, `createdByMe` | — | — |\n\nThe last three are standing personal views rather than a pinned item.\n\n`name` is a label you supply and the server never refreshes it, so a renamed project keeps its old favorite label until you update it." }, { "name": "favoriteFolder", "x-displayName": "Favorite Folder", "description": "A user-created folder for organizing favorite items in the sidebar" }, { "name": "file", "x-displayName": "File", "description": "An uploaded file attached to a project, task, document, message or folder. There is no content-type field: infer it from the extension in `name`." }, { "name": "form", "x-displayName": "Form", "description": "A form: a set of questions respondents answer, optionally wired to an automation that creates a task, document, message or check-in from each submission.\n\nThis surface covers form **structure**. Read submitted responses in the Nifty app.\n\nA form's questions are written as a whole: sending `fields` replaces the entire set, deleting anything you leave out. Keep a question by including its `id`. A form must always keep at least one question, may hold at most 200, and each question at most 100 choices." }, { "name": "goal", "x-displayName": "Goal", "description": "A team objective with tracked progress. `progressCompleted`, `progressTotal` and (for `targetType: dynamic`) `targetValue` are computed from the goal task set — send them and they are overwritten. A create needs at least `name` and `endAt`. A goal completes itself: `completedAt` is stamped when its tracked progress reaches its target and cleared when it falls back below. `members`, `tasks` and `lists` are honoured on create and ignored on update." }, { "name": "goalGroup", "x-displayName": "Goal Group", "description": "A team-scoped grouping for related goals (for example \"Q2 OKRs\"). It holds nothing but a name and a description; the goals themselves live on `/goals`. List a group's goals with `?expand=goals`, or with `GET /goals?goalGroupId[eq]={id}` when you want the full goal payloads. Groups have no intrinsic order — sort them however suits your UI." }, { "name": "label", "x-displayName": "Label", "description": "A tag you can apply across the workspace — to tasks, documents, files and more.\n\nLabels are workspace-wide; this surface has no project-scoped labels.\n\nNifty's seeded labels report `default: true` and are protected — renaming or deleting one returns **403**.\n\nDeleting a label moves it to the trash: `purgeAt` is then a FUTURE date, 30 days out, when it will be purged for good." }, { "name": "list", "x-displayName": "List", "description": "A project-scoped task container. By default a flat list (`isMilestone: false`); set `isMilestone: true` for a date-spanning milestone with start/end timestamps and timeline ordering." }, { "name": "member", "x-displayName": "Team Member", "description": "A person in the workspace — the author or assignee of most other resources.\n\n`theme` and `storyPointsCapacity` are writable only on your own member record; writing another member's returns 403 whatever your role." }, { "name": "message", "x-displayName": "Message", "description": "A message in a chat, task comment thread, document comment, file comment, annotation thread, or message thread (reply). Creating a message requires EXACTLY ONE parent context — set one of `chatId`, `taskId`, `documentId`, `fileId`, `annotationId` or `parentMessageId`, or set `recipientMemberId` to send a direct message to a team member (the 1:1 chat is created for you if it does not exist yet). `fileId` and `annotationId` are the one legal pair: send both to comment on a region of a file. Sending no context, or more than one, is rejected. Mention people with `tagged` and attach existing files with `files` in the same create call." }, { "name": "portfolio", "x-displayName": "Portfolio", "description": "A team-scoped grouping of projects. Carries name, icon, colors, ownership, and order metadata." }, { "name": "presenceStatus", "x-displayName": "Presence Status", "description": "A reusable status a member can switch on — \"In a meeting\", \"Focus time\", \"Out of office\". Templates are shared across the workspace.\n\nNifty seeds a starter set the first time someone opens the status picker in the app, so a workspace where nobody has done that returns an empty list even though the app will show six." }, { "name": "project", "x-displayName": "Project", "description": "A top-level container in the Nifty workspace. Projects hold tasks, lists, statuses, files, documents, members, and a project discussion chat. Scoped to a team; optionally grouped under a portfolio." }, { "name": "projectActivity", "x-displayName": "Project activity", "description": "The per-project activity feed: one append-only row per domain event. Rows are server-emitted — they cannot be created, edited or deleted. Pass `?projectId[eq]=` to fetch a single project’s feed. Exactly one of `taskId`, `listId`, `documentId` and `fileId` is set on any given row, determined by `type`; project-level events set none of them. The mapping is: `taskCompleted` → `taskId`; `listCreated`, `listMilestoneCreated` and `listUnlocked` → `listId`; `docCreated` → `documentId`; `fileUploaded` → `fileId`; `usersJoined` and `usersLeft` → `memberId`; `projectCreated` → none. Newest first by default." }, { "name": "projectDashboard", "x-displayName": "Project Dashboard", "description": "A named, shareable dashboard inside a project, made up of an ordered set of widget cards. The `widgets` array uses REPLACE semantics: the array you send becomes the complete set, so a PATCH that omits a widget DELETES it — omit the `widgets` key entirely to leave them untouched. Widget order is the order of the array." }, { "name": "projectFolder", "x-displayName": "Project Folder", "description": "A project folder — a grouping of projects inside a portfolio. To file a project into a folder, set that project's `projectFolderId`; set it to `null` to unfile. A folder belongs to exactly one portfolio and cannot be moved between portfolios." }, { "name": "recurringRule", "x-displayName": "Recurring Rule", "description": "A recurrence rule anchored to a task: while the rule is live, Nifty keeps spawning fresh copies of that task.\n\n`type` decides which configuration fields are legal, and the combinations are enforced — a mismatch is a 400, and even an explicit `null` counts as sending the field:\n\n| `type` | required | must be omitted |\n| --- | --- | --- |\n| `date` | `cron` **or** `schedule` | `triggerStatusId` |\n| `status` | `triggerStatusId` | `cron`, `schedule` |\n| `completion` | — | `cron`, `schedule`, `triggerStatusId` |\n\n`type` and `sourceTaskId` are fixed once the rule exists; everything else is editable. Only task-anchored rules are on this surface — rules attached to lists or check-ins are managed elsewhere and never appear here, so a list you know recurs may show no rule at all." }, { "name": "reminder", "x-displayName": "Reminder", "description": "A scheduled reminder anchored to a task. Fires a notification to its creator at `date`. `type` reads as a readable key: 'custom' (the only creatable kind — omit `type` and you get it) or 'overdue' (created by Nifty from task due dates; read-only). Create requires taskId (immutable after create). Reminders are personal — only their creator can see or change one. A reminder carries no message of its own: the notification is rendered from the task it is anchored to." }, { "name": "reportChart", "x-displayName": "Report Chart", "description": "A team-scoped saved reporting chart that aggregates task data (live, events, or historical) across one or more projects. Carries a chart type, a task filter, and a set of data series." }, { "name": "role", "x-displayName": "Role", "description": "A named permission set you assign to people in the workspace.\n\nYou may only grant permissions you hold yourself — a role that would exceed your own grant is refused. On update this is judged on the delta, so permissions the role already had can be carried forward.\n\nThe four built-in roles (owner, manager, regular, client) report `editable: false`: they accept a change to `initialScreen` and nothing else, and they cannot be deleted." }, { "name": "status", "x-displayName": "Status", "description": "A project-scoped status column for tasks (Kanban column, list stage). Carries a name, a hex color, a rank and an archived flag. Tasks reference their status by `statusId`. To mark a task done, set its `completed` flag. Completed tasks render in a virtual \"Completed\" column." }, { "name": "task", "x-displayName": "Task", "description": "A unit of work in a project. Carries name, description, status, assignees, labels, subscribers, due/start dates, parent task (for subtasks), list, archived flag, banner image and embed URL. Project-scoped — every task on this API lives inside a project, and the project is the security boundary; personal (project-less) tasks are not addressable here. Deletes are permanent: there is no trash or restore for a task. Setting `assignees`, `labels` or `subscribers` when you update a task replaces the whole set — use the matching sub-resource route, such as `POST /tasks/{id}/assignees`, to add or remove one at a time." }, { "name": "taskHandoff", "x-displayName": "Handoff", "description": "Working context for whoever picks a task up next — read the newest one of your kind before working a task, create one when you stop. Append-only: `summary` is the one line a person reads (what changed, what is next); `body` is JSON keyed by `body.schema` — `nifty.checkpoint/1` is validated, any other `./` is stored as-is. Newest of a kind wins; never edit an old one (there is no update). List with `taskId` and `schema` filters, `limit: 1` for the latest." }, { "name": "timeEntry", "x-displayName": "Time Entry", "description": "A tracked interval of work on a task.\n\n**Whose entries you see depends on your role.** By default list, get and search return only your own entries. If your role holds viewTimeReports, list and get return every entry in your team, and `memberId` narrows that to one person — this is how a team-wide time report is built.\n\nNote for integrations: breadth follows the ROLE, not the token. A token granted time-entry read by someone holding viewTimeReports can read that whole team, not only the person who granted it.\n\n`search` is the exception: it stays scoped to your own entries whatever your role, so it under-reports a team. Use list for reporting.\n\nOmit `end` (or send null) to start a running entry, then PATCH `end` to stop it. `taskId` and `projectId` are set once: an entry cannot be moved to another task or project afterwards." }, { "name": "webhook", "x-displayName": "Webhook", "description": "Webhook subscriptions. Register an HTTPS endpoint, choose which events it receives, and Nifty POSTs each matching event to it signed with an HMAC-SHA256 secret. That secret is returned exactly once — at creation, and again from rotateSecret — and is never readable afterwards." } ], "paths": { "/actors": { "get": { "summary": "List Actors", "description": "List actors. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `displayName` unless you pass `sort`.\n\n**Required scope:** `actors:read`", "operationId": "listActors", "tags": [ "actor" ], "x-required-scopes": [ "actors:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `displayName`.", "schema": { "type": "string", "enum": [ "displayName", "type", "-displayName", "-type" ] }, "example": "displayName" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "id[eq]", "in": "query", "required": false, "description": "Filter where `id` equals.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013" }, { "name": "id[in]", "in": "query", "required": false, "description": "Filter where `id` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "example": [ "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013", "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ] }, "example": "human" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ] } }, "example": [ "human", "agent" ] }, { "name": "memberId[eq]", "in": "query", "required": false, "description": "Filter where `memberId` equals.", "schema": { "type": "string" }, "example": "P3hYIKqK" }, { "name": "memberId[in]", "in": "query", "required": false, "description": "Filter where `memberId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "P3hYIKqK", "P3hYIKqK" ] }, { "name": "agentId[eq]", "in": "query", "required": false, "description": "Filter where `agentId` equals.", "schema": { "type": "string" }, "example": "8EO45hmm" }, { "name": "agentId[in]", "in": "query", "required": false, "description": "Filter where `agentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "8EO45hmm", "8EO45hmm" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/actor" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013", "type": "human", "displayName": "Example", "memberId": "P3hYIKqK", "agentId": "8EO45hmm", "tombstonedAt": "2026-06-30T12:00:00.000Z" }, { "id": "db9b7c99-d89b-4d99-8de9-df9b82e5fe95", "type": "human", "displayName": "Example", "memberId": "P3hYIKqK", "agentId": "8EO45hmm", "tombstonedAt": "2026-06-30T12:00:00.000Z" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "actors:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/actors\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/actors');" } ] } }, "/actors/{id}": { "get": { "summary": "Get Actor", "description": "Retrieve a single Actor by id.\n\n**Required scope:** `actors:read`", "operationId": "getActor", "tags": [ "actor" ], "x-required-scopes": [ "actors:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Actor.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "aheWuoWg" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/actor" }, "examples": { "default": { "value": { "id": "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013", "type": "human", "displayName": "Example", "memberId": "P3hYIKqK", "agentId": "8EO45hmm", "tombstonedAt": "2026-06-30T12:00:00.000Z" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "actors:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/actors/aheWuoWg\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/actors/{id}', {\n params: { path: { id: 'aheWuoWg' } },\n});" } ] } }, "/annotations": { "get": { "summary": "List Annotations", "description": "List annotations. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `annotations:read`", "operationId": "listAnnotations", "tags": [ "annotation" ], "x-required-scopes": [ "annotations:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "-createdAt", "-updatedAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "file", "task", "messages", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "file", "task" ] }, { "name": "fileId[eq]", "in": "query", "required": false, "description": "Filter where `fileId` equals.", "schema": { "type": "string" }, "example": "xvM2toUM" }, { "name": "fileId[in]", "in": "query", "required": false, "description": "Filter where `fileId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "xvM2toUM", "xvM2toUM" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "videoTimeSeconds[eq]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` equals.", "schema": { "type": "number" }, "example": 42.5 }, { "name": "videoTimeSeconds[gt]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` is greater than.", "schema": { "type": "number" }, "example": 42.5 }, { "name": "videoTimeSeconds[gte]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` is greater than or equal to.", "schema": { "type": "number" }, "example": 42.5 }, { "name": "videoTimeSeconds[lt]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` is less than.", "schema": { "type": "number" }, "example": 42.5 }, { "name": "videoTimeSeconds[lte]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` is less than or equal to.", "schema": { "type": "number" }, "example": 42.5 }, { "name": "videoTimeSeconds[null]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "videoTimeSeconds[notNull]", "in": "query", "required": false, "description": "Filter where `videoTimeSeconds` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "image", "video" ] }, "example": "image" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "image", "video" ] } }, "example": [ "image", "video" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/annotationExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "863BiyIc", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "image", "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "fileId": "xvM2toUM", "taskId": "KfS0ha8P", "messages": [] }, { "id": "ez6jIQsM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "image", "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "fileId": "xvM2toUM", "taskId": "KfS0ha8P", "messages": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "annotations:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/annotations\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/annotations');" } ] }, "post": { "summary": "Create Annotation", "description": "Create an Annotation. Server-assigned fields are ignored if sent.\n\n**Required scope:** `annotations:write`", "operationId": "createAnnotation", "tags": [ "annotation" ], "x-required-scopes": [ "annotations:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "file", "task", "messages", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "file", "task" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/annotationCreate" }, "examples": { "default": { "value": { "type": "image", "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "fileId": "xvM2toUM" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/annotationExpanded" }, "examples": { "default": { "value": { "id": "863BiyIc", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "image", "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "fileId": "xvM2toUM", "taskId": "KfS0ha8P", "messages": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "annotations:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/annotations\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"type\":\"image\",\"geometry\":{\"type\":\"RECTANGLE\",\"x\":12.5,\"y\":40,\"width\":25,\"height\":10},\"videoTimeSeconds\":42.5,\"fileId\":\"xvM2toUM\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/annotations', {\n body: {\n \"type\": \"image\",\n \"geometry\": {\n \"type\": \"RECTANGLE\",\n \"x\": 12.5,\n \"y\": 40,\n \"width\": 25,\n \"height\": 10\n },\n \"videoTimeSeconds\": 42.5,\n \"fileId\": \"xvM2toUM\"\n },\n});" } ] } }, "/annotations/{id}": { "get": { "summary": "Get Annotation", "description": "Retrieve a single Annotation by id.\n\n**Required scope:** `annotations:read`", "operationId": "getAnnotation", "tags": [ "annotation" ], "x-required-scopes": [ "annotations:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Annotation.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "863BiyIc" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "file", "task", "messages", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "file", "task" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/annotationExpanded" }, "examples": { "default": { "value": { "id": "863BiyIc", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "image", "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "fileId": "xvM2toUM", "taskId": "KfS0ha8P", "messages": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "annotations:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/annotations/863BiyIc\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/annotations/{id}', {\n params: { path: { id: '863BiyIc' } },\n});" } ] }, "patch": { "summary": "Update Annotation", "description": "Partially update an Annotation. Only the fields you send are changed.\n\n**Required scope:** `annotations:write`", "operationId": "updateAnnotation", "tags": [ "annotation" ], "x-required-scopes": [ "annotations:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Annotation.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "863BiyIc" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "file", "task", "messages", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "file", "task" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/annotationUpdate" }, "examples": { "default": { "value": { "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/annotationExpanded" }, "examples": { "default": { "value": { "id": "863BiyIc", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "image", "geometry": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "videoTimeSeconds": 42.5, "fileId": "xvM2toUM", "taskId": "KfS0ha8P", "messages": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "annotations:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/annotations/863BiyIc\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"geometry\":{\"type\":\"RECTANGLE\",\"x\":12.5,\"y\":40,\"width\":25,\"height\":10},\"videoTimeSeconds\":42.5,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/annotations/{id}', {\n params: { path: { id: '863BiyIc' } },\n body: {\n \"geometry\": {\n \"type\": \"RECTANGLE\",\n \"x\": 12.5,\n \"y\": 40,\n \"width\": 25,\n \"height\": 10\n },\n \"videoTimeSeconds\": 42.5,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Annotation", "description": "Permanently delete this Annotation. This cannot be undone. The annotation's comment thread is deleted with it.\n\n**Required scope:** `annotations:delete`", "operationId": "deleteAnnotation", "tags": [ "annotation" ], "x-required-scopes": [ "annotations:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Annotation.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "863BiyIc" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "annotations:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/annotations/863BiyIc\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/annotations/{id}', {\n params: { path: { id: '863BiyIc' } },\n});" } ] } }, "/chats": { "get": { "summary": "List Chats", "description": "List chats. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by `lastMessageAt` unless you pass `sort`.\n\n**Required scope:** `chats:read`", "operationId": "listChats", "tags": [ "chat" ], "x-required-scopes": [ "chats:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `lastMessageAt`.", "schema": { "type": "string", "enum": [ "name", "lastMessageAt", "createdAt", "-name", "-lastMessageAt", "-createdAt" ] }, "example": "lastMessageAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "members", "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "members", "project" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "group", "direct", "project" ] }, "example": "group" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "group", "direct", "project" ] } }, "example": [ "group", "direct" ] }, { "name": "lastMessageAt[gt]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "lastMessageAt[gte]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "lastMessageAt[lt]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "lastMessageAt[lte]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "recipientMemberId[eq]", "in": "query", "required": false, "description": "Filter where `recipientMemberId` equals.", "schema": { "type": "string" }, "example": "AdeWqOs6" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/chatExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "hTIeouEK", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] }, { "id": "Vnky67TE", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "chats:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/chats\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/chats');" } ] }, "post": { "summary": "Create Chat", "description": "Create a Chat. Server-assigned fields are ignored if sent.\n\n**Required scope:** `chats:write`", "operationId": "createChat", "tags": [ "chat" ], "x-required-scopes": [ "chats:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "members", "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "members", "project" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chatCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "type": "group", "memberIds": [ "8oqm2XKk" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chatExpanded" }, "examples": { "default": { "value": { "id": "hTIeouEK", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "chats:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/chats\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"type\":\"group\",\"memberIds\":[\"8oqm2XKk\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/chats', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"type\": \"group\",\n \"memberIds\": [\n \"8oqm2XKk\"\n ]\n },\n});" } ] } }, "/chats/{id}": { "get": { "summary": "Get Chat", "description": "Retrieve a single Chat by id.\n\n**Required scope:** `chats:read`", "operationId": "getChat", "tags": [ "chat" ], "x-required-scopes": [ "chats:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Chat.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "hTIeouEK" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "members", "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "members", "project" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chatExpanded" }, "examples": { "default": { "value": { "id": "hTIeouEK", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "chats:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/chats/hTIeouEK\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/chats/{id}', {\n params: { path: { id: 'hTIeouEK' } },\n});" } ] }, "patch": { "summary": "Update Chat", "description": "Partially update a Chat. Only the fields you send are changed.\n\n**Required scope:** `chats:write`", "operationId": "updateChat", "tags": [ "chat" ], "x-required-scopes": [ "chats:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Chat.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "hTIeouEK" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "members", "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "members", "project" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chatUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chatExpanded" }, "examples": { "default": { "value": { "id": "hTIeouEK", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "chats:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/chats/hTIeouEK\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/chats/{id}', {\n params: { path: { id: 'hTIeouEK' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Chat", "description": "Permanently delete this Chat. This cannot be undone. Every message in the chat is deleted with it.\n\n**Required scope:** `chats:delete`", "operationId": "deleteChat", "tags": [ "chat" ], "x-required-scopes": [ "chats:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Chat.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "hTIeouEK" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "chats:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/chats/hTIeouEK\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/chats/{id}', {\n params: { path: { id: 'hTIeouEK' } },\n});" } ] } }, "/chats/search": { "get": { "summary": "Search Chats", "description": "Full-text ranked search across chats. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.\n\n**Required scope:** `chats:read`", "operationId": "searchChats", "tags": [ "chat" ], "x-required-scopes": [ "chats:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "members", "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "members", "project" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "group", "direct", "project" ] }, "example": "group" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "group", "direct", "project" ] } }, "example": [ "group", "direct" ] }, { "name": "lastMessageAt[gt]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "lastMessageAt[gte]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "lastMessageAt[lt]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "lastMessageAt[lte]", "in": "query", "required": false, "description": "Filter where `lastMessageAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-02T18:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "recipientMemberId[eq]", "in": "query", "required": false, "description": "Filter where `recipientMemberId` equals.", "schema": { "type": "string" }, "example": "AdeWqOs6" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/chatExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "hTIeouEK", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] }, { "id": "Vnky67TE", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "description": "A concise description.", "type": "group", "teamId": "cfC83TeS", "projectId": "iV6vIU8N", "pinnedMessageId": "ytAkOyYK", "lastMessageAt": "2026-06-02T18:00:00.000Z", "members": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "chats:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/chats/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/chats/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/check-ins": { "get": { "summary": "List Check-ins", "description": "List checkIns. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 7 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `check-ins:read`", "operationId": "listCheckIns", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "updatedAt", "-name", "-createdAt", "-updatedAt" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "form", "recurringRule", "createdByActor", "assignees", "subscribers", "requests" ] } }, "style": "form", "explode": false, "example": [ "form", "recurringRule" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "requestType[eq]", "in": "query", "required": false, "description": "Filter where `requestType` equals.", "schema": { "type": "string", "enum": [ "schedule", "manual" ] }, "example": "schedule" }, { "name": "requestType[in]", "in": "query", "required": false, "description": "Filter where `requestType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "schedule", "manual" ] } }, "example": [ "schedule", "manual" ] }, { "name": "formId[eq]", "in": "query", "required": false, "description": "Filter where `formId` equals.", "schema": { "type": "string" }, "example": "Jt0ByAIi" }, { "name": "formId[in]", "in": "query", "required": false, "description": "Filter where `formId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Jt0ByAIi", "Jt0ByAIi" ] }, { "name": "recurringRuleId[eq]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` equals.", "schema": { "type": "string" }, "example": "cn2v0xiQ" }, { "name": "recurringRuleId[in]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "cn2v0xiQ", "cn2v0xiQ" ] }, { "name": "createdByActorId[eq]", "in": "query", "required": false, "description": "Filter where `createdByActorId` equals.", "schema": { "type": "string" }, "example": "49f861f7-4af8-44bf-844f-45f85babe504" }, { "name": "createdByActorId[in]", "in": "query", "required": false, "description": "Filter where `createdByActorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "49f861f7-4af8-44bf-844f-45f85babe504", "49f861f7-4af8-44bf-844f-45f85babe504" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/checkInExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "8cQSsSK8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" }, { "id": "pVSc4PSq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/check-ins\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/check-ins');" } ] }, "post": { "summary": "Create Check-in", "description": "Create a Check-in. Server-assigned fields are ignored if sent.\n\n**Required scope:** `check-ins:write`", "operationId": "createCheckIn", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "form", "recurringRule", "createdByActor", "assignees", "subscribers", "requests" ] } }, "style": "form", "explode": false, "example": [ "form", "recurringRule" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInCreate" }, "examples": { "default": { "value": { "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ", "schedule": {}, "assignees": [ "CNIgSuay" ], "subscribers": [ "NlUEieKe" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInExpanded" }, "examples": { "default": { "value": { "id": "8cQSsSK8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-ins\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"notifyTypes\":[\"email\"],\"requestType\":\"schedule\",\"formId\":\"Jt0ByAIi\",\"recurringRuleId\":\"cn2v0xiQ\",\"schedule\":{},\"assignees\":[\"CNIgSuay\"],\"subscribers\":[\"NlUEieKe\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-ins', {\n body: {\n \"name\": \"Example\",\n \"notifyTypes\": [\n \"email\"\n ],\n \"requestType\": \"schedule\",\n \"formId\": \"Jt0ByAIi\",\n \"recurringRuleId\": \"cn2v0xiQ\",\n \"schedule\": {},\n \"assignees\": [\n \"CNIgSuay\"\n ],\n \"subscribers\": [\n \"NlUEieKe\"\n ]\n },\n});" } ] } }, "/check-ins/{id}": { "get": { "summary": "Get Check-in", "description": "Retrieve a single Check-in by id.\n\n**Required scope:** `check-ins:read`", "operationId": "getCheckIn", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "form", "recurringRule", "createdByActor", "assignees", "subscribers", "requests" ] } }, "style": "form", "explode": false, "example": [ "form", "recurringRule" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInExpanded" }, "examples": { "default": { "value": { "id": "8cQSsSK8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/check-ins/{id}', {\n params: { path: { id: '8cQSsSK8' } },\n});" } ] }, "patch": { "summary": "Update Check-in", "description": "Partially update a Check-in. Only the fields you send are changed.\n\n**Required scope:** `check-ins:write`", "operationId": "updateCheckIn", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "form", "recurringRule", "createdByActor", "assignees", "subscribers", "requests" ] } }, "style": "form", "explode": false, "example": [ "form", "recurringRule" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInUpdate" }, "examples": { "default": { "value": { "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "recurringRuleId": "cn2v0xiQ", "assignees": [ "CNIgSuay" ], "subscribers": [ "NlUEieKe" ], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInExpanded" }, "examples": { "default": { "value": { "id": "8cQSsSK8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"notifyTypes\":[\"email\"],\"requestType\":\"schedule\",\"recurringRuleId\":\"cn2v0xiQ\",\"assignees\":[\"CNIgSuay\"],\"subscribers\":[\"NlUEieKe\"],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/check-ins/{id}', {\n params: { path: { id: '8cQSsSK8' } },\n body: {\n \"name\": \"Example\",\n \"notifyTypes\": [\n \"email\"\n ],\n \"requestType\": \"schedule\",\n \"recurringRuleId\": \"cn2v0xiQ\",\n \"assignees\": [\n \"CNIgSuay\"\n ],\n \"subscribers\": [\n \"NlUEieKe\"\n ],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Check-in", "description": "Permanently delete this Check-in. This cannot be undone.\n\n**Required scope:** `check-ins:delete`", "operationId": "deleteCheckIn", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/check-ins/{id}', {\n params: { path: { id: '8cQSsSK8' } },\n});" } ] } }, "/check-ins/search": { "get": { "summary": "Search Check-ins", "description": "Full-text ranked search across checkIns. Ranked by relevance; pages are capped at 200 results. Filterable by 7 fields.\n\n**Required scope:** `check-ins:read`", "operationId": "searchCheckIns", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "form", "recurringRule", "createdByActor", "assignees", "subscribers", "requests" ] } }, "style": "form", "explode": false, "example": [ "form", "recurringRule" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "requestType[eq]", "in": "query", "required": false, "description": "Filter where `requestType` equals.", "schema": { "type": "string", "enum": [ "schedule", "manual" ] }, "example": "schedule" }, { "name": "requestType[in]", "in": "query", "required": false, "description": "Filter where `requestType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "schedule", "manual" ] } }, "example": [ "schedule", "manual" ] }, { "name": "formId[eq]", "in": "query", "required": false, "description": "Filter where `formId` equals.", "schema": { "type": "string" }, "example": "Jt0ByAIi" }, { "name": "formId[in]", "in": "query", "required": false, "description": "Filter where `formId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Jt0ByAIi", "Jt0ByAIi" ] }, { "name": "recurringRuleId[eq]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` equals.", "schema": { "type": "string" }, "example": "cn2v0xiQ" }, { "name": "recurringRuleId[in]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "cn2v0xiQ", "cn2v0xiQ" ] }, { "name": "createdByActorId[eq]", "in": "query", "required": false, "description": "Filter where `createdByActorId` equals.", "schema": { "type": "string" }, "example": "49f861f7-4af8-44bf-844f-45f85babe504" }, { "name": "createdByActorId[in]", "in": "query", "required": false, "description": "Filter where `createdByActorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "49f861f7-4af8-44bf-844f-45f85babe504", "49f861f7-4af8-44bf-844f-45f85babe504" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/checkInExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "8cQSsSK8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" }, { "id": "pVSc4PSq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "notifyTypes": [ "email" ], "requestType": "schedule", "formId": "Jt0ByAIi", "recurringRuleId": "cn2v0xiQ" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/check-ins/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/check-ins/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/check-ins/{id}/assignees": { "post": { "summary": "Add assignees to a Check-in", "description": "Link the given ids to this Check-in as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `check-ins:write` `check-ins:link`", "operationId": "addCheckInAssignees", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:write", "check-ins:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:write", "check-ins:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8/assignees\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-ins/{id}/assignees', {\n params: { path: { id: '8cQSsSK8' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/check-ins/{id}/assignees/remove": { "post": { "summary": "Remove assignees from a Check-in", "description": "Unlink the given ids from this Check-in's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `check-ins:write` `check-ins:link`", "operationId": "removeCheckInAssignees", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:write", "check-ins:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:write", "check-ins:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8/assignees/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-ins/{id}/assignees/remove', {\n params: { path: { id: '8cQSsSK8' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/check-ins/{id}/subscribers": { "post": { "summary": "Add subscribers to a Check-in", "description": "Link the given ids to this Check-in as subscribers. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete subscribers set afterwards.\n\n**Required scopes:** `check-ins:write` `check-ins:link`", "operationId": "addCheckInSubscribers", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:write", "check-ins:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete subscribers set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:write", "check-ins:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8/subscribers\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-ins/{id}/subscribers', {\n params: { path: { id: '8cQSsSK8' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/check-ins/{id}/subscribers/remove": { "post": { "summary": "Remove subscribers from a Check-in", "description": "Unlink the given ids from this Check-in's subscribers. Removing one that is not linked changes nothing. Returns the complete subscribers set afterwards.\n\n**Required scopes:** `check-ins:write` `check-ins:link`", "operationId": "removeCheckInSubscribers", "tags": [ "checkIn" ], "x-required-scopes": [ "check-ins:write", "check-ins:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "8cQSsSK8" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete subscribers set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-ins:write", "check-ins:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-ins/8cQSsSK8/subscribers/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-ins/{id}/subscribers/remove', {\n params: { path: { id: '8cQSsSK8' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/check-in-requests": { "get": { "summary": "List Check-in requests", "description": "List checkInRequests. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `check-in-requests:read`", "operationId": "listCheckInRequests", "tags": [ "checkInRequest" ], "x-required-scopes": [ "check-in-requests:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`.", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "reminderSentAt", "-createdAt", "-updatedAt", "-reminderSentAt" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checkIn", "assignees", "respondedBy" ] } }, "style": "form", "explode": false, "example": [ "checkIn", "assignees" ] }, { "name": "checkInId[eq]", "in": "query", "required": false, "description": "Filter where `checkInId` equals.", "schema": { "type": "string" }, "example": "8cQSsSK8" }, { "name": "checkInId[in]", "in": "query", "required": false, "description": "Filter where `checkInId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "8cQSsSK8", "8cQSsSK8" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "reminderSentAt[gt]", "in": "query", "required": false, "description": "Filter where `reminderSentAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-08T09:00:00.000Z" }, { "name": "reminderSentAt[gte]", "in": "query", "required": false, "description": "Filter where `reminderSentAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-08T09:00:00.000Z" }, { "name": "reminderSentAt[lt]", "in": "query", "required": false, "description": "Filter where `reminderSentAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-08T09:00:00.000Z" }, { "name": "reminderSentAt[lte]", "in": "query", "required": false, "description": "Filter where `reminderSentAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-08T09:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/checkInRequestExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "fVCU89x0", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "checkInId": "8cQSsSK8", "reminderSentAt": "2026-06-08T09:00:00.000Z", "assignees": [], "respondedBy": [] }, { "id": "OnksMOi6", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "checkInId": "8cQSsSK8", "reminderSentAt": "2026-06-08T09:00:00.000Z", "assignees": [], "respondedBy": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-in-requests:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/check-in-requests\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/check-in-requests');" } ] }, "post": { "summary": "Create Check-in request", "description": "Create a Check-in request. Server-assigned fields are ignored if sent.\n\n**Required scope:** `check-in-requests:write`", "operationId": "createCheckInRequest", "tags": [ "checkInRequest" ], "x-required-scopes": [ "check-in-requests:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checkIn", "assignees", "respondedBy" ] } }, "style": "form", "explode": false, "example": [ "checkIn", "assignees" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInRequestCreate" }, "examples": { "default": { "value": { "checkInId": "8cQSsSK8", "assignees": [ "CNIgSuay" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInRequestExpanded" }, "examples": { "default": { "value": { "id": "fVCU89x0", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "checkInId": "8cQSsSK8", "reminderSentAt": "2026-06-08T09:00:00.000Z", "assignees": [], "respondedBy": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-in-requests:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-in-requests\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"checkInId\":\"8cQSsSK8\",\"assignees\":[\"CNIgSuay\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-in-requests', {\n body: {\n \"checkInId\": \"8cQSsSK8\",\n \"assignees\": [\n \"CNIgSuay\"\n ]\n },\n});" } ] } }, "/check-in-requests/{id}": { "get": { "summary": "Get Check-in request", "description": "Retrieve a single Check-in request by id.\n\n**Required scope:** `check-in-requests:read`", "operationId": "getCheckInRequest", "tags": [ "checkInRequest" ], "x-required-scopes": [ "check-in-requests:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in request.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "fVCU89x0" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checkIn", "assignees", "respondedBy" ] } }, "style": "form", "explode": false, "example": [ "checkIn", "assignees" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkInRequestExpanded" }, "examples": { "default": { "value": { "id": "fVCU89x0", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "checkInId": "8cQSsSK8", "reminderSentAt": "2026-06-08T09:00:00.000Z", "assignees": [], "respondedBy": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-in-requests:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/check-in-requests/fVCU89x0\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/check-in-requests/{id}', {\n params: { path: { id: 'fVCU89x0' } },\n});" } ] }, "delete": { "summary": "Delete Check-in request", "description": "Permanently delete this Check-in request. This cannot be undone.\n\n**Required scope:** `check-in-requests:delete`", "operationId": "deleteCheckInRequest", "tags": [ "checkInRequest" ], "x-required-scopes": [ "check-in-requests:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in request.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "fVCU89x0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-in-requests:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/check-in-requests/fVCU89x0\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/check-in-requests/{id}', {\n params: { path: { id: 'fVCU89x0' } },\n});" } ] } }, "/check-in-requests/{id}/assignees": { "post": { "summary": "Add assignees to a Check-in request", "description": "Link the given ids to this Check-in request as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `check-in-requests:write` `check-in-requests:link`", "operationId": "addCheckInRequestAssignees", "tags": [ "checkInRequest" ], "x-required-scopes": [ "check-in-requests:write", "check-in-requests:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in request.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "fVCU89x0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-in-requests:write", "check-in-requests:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-in-requests/fVCU89x0/assignees\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-in-requests/{id}/assignees', {\n params: { path: { id: 'fVCU89x0' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/check-in-requests/{id}/assignees/remove": { "post": { "summary": "Remove assignees from a Check-in request", "description": "Unlink the given ids from this Check-in request's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `check-in-requests:write` `check-in-requests:link`", "operationId": "removeCheckInRequestAssignees", "tags": [ "checkInRequest" ], "x-required-scopes": [ "check-in-requests:write", "check-in-requests:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Check-in request.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "fVCU89x0" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "check-in-requests:write", "check-in-requests:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/check-in-requests/fVCU89x0/assignees/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/check-in-requests/{id}/assignees/remove', {\n params: { path: { id: 'fVCU89x0' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/checklists": { "get": { "summary": "List Checklists", "description": "List checklists. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `checklists:read`", "operationId": "listChecklists", "tags": [ "checklist" ], "x-required-scopes": [ "checklists:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list checklists across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "-name", "-order", "-createdAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "checklistItems", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "checklistItems" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/checklistExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "NrmgIiU8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "taskId": "KfS0ha8P" }, { "id": "4MisMIsY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "order": 101, "taskId": "KfS0ha8P" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklists:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/checklists\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/checklists');" } ] }, "post": { "summary": "Create Checklist", "description": "Create a Checklist. Server-assigned fields are ignored if sent.\n\n**Required scope:** `checklists:write`", "operationId": "createChecklist", "tags": [ "checklist" ], "x-required-scopes": [ "checklists:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "checklistItems", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "checklistItems" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistCreate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "taskId": "KfS0ha8P" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistExpanded" }, "examples": { "default": { "value": { "id": "NrmgIiU8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "taskId": "KfS0ha8P" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklists:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/checklists\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"taskId\":\"KfS0ha8P\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/checklists', {\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"taskId\": \"KfS0ha8P\"\n },\n});" } ] } }, "/checklists/{id}": { "get": { "summary": "Get Checklist", "description": "Retrieve a single Checklist by id.\n\n**Required scope:** `checklists:read`", "operationId": "getChecklist", "tags": [ "checklist" ], "x-required-scopes": [ "checklists:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Checklist.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "NrmgIiU8" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "checklistItems", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "checklistItems" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistExpanded" }, "examples": { "default": { "value": { "id": "NrmgIiU8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "taskId": "KfS0ha8P" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklists:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/checklists/NrmgIiU8\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/checklists/{id}', {\n params: { path: { id: 'NrmgIiU8' } },\n});" } ] }, "patch": { "summary": "Update Checklist", "description": "Partially update a Checklist. Only the fields you send are changed.\n\n**Required scope:** `checklists:write`", "operationId": "updateChecklist", "tags": [ "checklist" ], "x-required-scopes": [ "checklists:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Checklist.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "NrmgIiU8" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "checklistItems", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "checklistItems" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistUpdate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistExpanded" }, "examples": { "default": { "value": { "id": "NrmgIiU8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "taskId": "KfS0ha8P" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklists:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/checklists/NrmgIiU8\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/checklists/{id}', {\n params: { path: { id: 'NrmgIiU8' } },\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Checklist", "description": "Permanently delete this Checklist. This cannot be undone.\n\n**Required scope:** `checklists:delete`", "operationId": "deleteChecklist", "tags": [ "checklist" ], "x-required-scopes": [ "checklists:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Checklist.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "NrmgIiU8" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklists:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/checklists/NrmgIiU8\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/checklists/{id}', {\n params: { path: { id: 'NrmgIiU8' } },\n});" } ] } }, "/checklist-items": { "get": { "summary": "List Checklist Items", "description": "List checklistItems. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `checklist-items:read`", "operationId": "listChecklistItems", "tags": [ "checklistItem" ], "x-required-scopes": [ "checklist-items:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list checklistItems across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "-name", "-order", "-createdAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checklist", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "checklist", "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "checklistId[eq]", "in": "query", "required": false, "description": "Filter where `checklistId` equals.", "schema": { "type": "string" }, "example": "NrmgIiU8" }, { "name": "checklistId[in]", "in": "query", "required": false, "description": "Filter where `checklistId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "NrmgIiU8", "NrmgIiU8" ] }, { "name": "completed[eq]", "in": "query", "required": false, "description": "Filter where `completed` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/checklistItemExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "iLCQkeWQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "completed": false, "checklistId": "NrmgIiU8" }, { "id": "Irs0jGsE", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "order": 101, "completed": false, "checklistId": "NrmgIiU8" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklist-items:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/checklist-items\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/checklist-items');" } ] }, "post": { "summary": "Create Checklist Item", "description": "Create a Checklist Item. Server-assigned fields are ignored if sent.\n\n**Required scope:** `checklist-items:write`", "operationId": "createChecklistItem", "tags": [ "checklistItem" ], "x-required-scopes": [ "checklist-items:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checklist", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "checklist", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistItemCreate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "completed": false, "checklistId": "NrmgIiU8" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistItemExpanded" }, "examples": { "default": { "value": { "id": "iLCQkeWQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "completed": false, "checklistId": "NrmgIiU8" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklist-items:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/checklist-items\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"completed\":false,\"checklistId\":\"NrmgIiU8\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/checklist-items', {\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"completed\": false,\n \"checklistId\": \"NrmgIiU8\"\n },\n});" } ] } }, "/checklist-items/{id}": { "get": { "summary": "Get Checklist Item", "description": "Retrieve a single Checklist Item by id.\n\n**Required scope:** `checklist-items:read`", "operationId": "getChecklistItem", "tags": [ "checklistItem" ], "x-required-scopes": [ "checklist-items:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Checklist Item.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iLCQkeWQ" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checklist", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "checklist", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistItemExpanded" }, "examples": { "default": { "value": { "id": "iLCQkeWQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "completed": false, "checklistId": "NrmgIiU8" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklist-items:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/checklist-items/iLCQkeWQ\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/checklist-items/{id}', {\n params: { path: { id: 'iLCQkeWQ' } },\n});" } ] }, "patch": { "summary": "Update Checklist Item", "description": "Partially update a Checklist Item. Only the fields you send are changed.\n\n**Required scope:** `checklist-items:write`", "operationId": "updateChecklistItem", "tags": [ "checklistItem" ], "x-required-scopes": [ "checklist-items:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Checklist Item.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iLCQkeWQ" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "checklist", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "checklist", "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistItemUpdate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "completed": false, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checklistItemExpanded" }, "examples": { "default": { "value": { "id": "iLCQkeWQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 100, "completed": false, "checklistId": "NrmgIiU8" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklist-items:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/checklist-items/iLCQkeWQ\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"completed\":false,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/checklist-items/{id}', {\n params: { path: { id: 'iLCQkeWQ' } },\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"completed\": false,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Checklist Item", "description": "Permanently delete this Checklist Item. This cannot be undone.\n\n**Required scope:** `checklist-items:delete`", "operationId": "deleteChecklistItem", "tags": [ "checklistItem" ], "x-required-scopes": [ "checklist-items:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Checklist Item.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iLCQkeWQ" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "checklist-items:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/checklist-items/iLCQkeWQ\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/checklist-items/{id}', {\n params: { path: { id: 'iLCQkeWQ' } },\n});" } ] } }, "/custom-fields": { "get": { "summary": "List Custom Fields", "description": "List customFields. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `name` unless you pass `sort`.\n\n**Required scope:** `custom-fields:read`", "operationId": "listCustomFields", "tags": [ "customField" ], "x-required-scopes": [ "custom-fields:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `name`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "name" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "options", "hiddenFor" ] } }, "style": "form", "explode": false, "example": [ "options", "hiddenFor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "dropdown", "text", "reminder", "number", "url", "phone", "email", "location", "currency", "checkbox", "budget", "calc", "date", "user", "datesdiff" ] }, "example": "dropdown" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "dropdown", "text", "reminder", "number", "url", "phone", "email", "location", "currency", "checkbox", "budget", "calc", "date", "user", "datesdiff" ] } }, "example": [ "dropdown", "text" ] }, { "name": "inLibrary[eq]", "in": "query", "required": false, "description": "Filter where `inLibrary` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/customField" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "6GWCcskG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "description": "A concise description.", "type": "dropdown", "associations": [ "task", "project" ], "currency": "USD", "inLibrary": false, "teamId": "cfC83TeS", "options": [], "hiddenFor": [] }, { "id": "kVSsggmU", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Second example", "description": "A concise description.", "type": "dropdown", "associations": [ "task", "project" ], "currency": "USD", "inLibrary": false, "teamId": "cfC83TeS", "options": [], "hiddenFor": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "custom-fields:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/custom-fields\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/custom-fields');" } ] } }, "/custom-fields/{id}": { "get": { "summary": "Get Custom Field", "description": "Retrieve a single Custom Field by id.\n\n**Required scope:** `custom-fields:read`", "operationId": "getCustomField", "tags": [ "customField" ], "x-required-scopes": [ "custom-fields:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Custom Field.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "6GWCcskG" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "options", "hiddenFor" ] } }, "style": "form", "explode": false, "example": [ "options", "hiddenFor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customField" }, "examples": { "default": { "value": { "id": "6GWCcskG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "description": "A concise description.", "type": "dropdown", "associations": [ "task", "project" ], "currency": "USD", "inLibrary": false, "teamId": "cfC83TeS", "options": [], "hiddenFor": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "custom-fields:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/custom-fields/6GWCcskG\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/custom-fields/{id}', {\n params: { path: { id: '6GWCcskG' } },\n});" } ] } }, "/documents": { "get": { "summary": "List Documents", "description": "List documents. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 9 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `documents:read`", "operationId": "listDocuments", "tags": [ "document" ], "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list documents across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "author", "parentDocument", "deletedBy", "createdByActor", "updatedByActor", "labels" ] } }, "style": "form", "explode": false, "example": [ "project", "author" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "parentDocumentId[eq]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` equals.", "schema": { "type": "string" }, "example": "429XYeO6" }, { "name": "parentDocumentId[in]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "429XYeO6", "429XYeO6" ] }, { "name": "parentDocumentId[null]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "parentDocumentId[notNull]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "nifty", "google", "dropbox", "microsoft" ] }, "example": "nifty" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "nifty", "google", "dropbox", "microsoft" ] } }, "example": [ "nifty", "google" ] }, { "name": "accessType[eq]", "in": "query", "required": false, "description": "Filter where `accessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited", "private" ] }, "example": "public" }, { "name": "accessType[in]", "in": "query", "required": false, "description": "Filter where `accessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited", "private" ] } }, "example": [ "public", "limited" ] }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "editorVersion[eq]", "in": "query", "required": false, "description": "Filter where `editorVersion` equals.", "schema": { "type": "number" }, "example": 2 }, { "name": "editorVersion[in]", "in": "query", "required": false, "description": "Filter where `editorVersion` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "number" } }, "example": [ 2, 2 ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/documentExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "ELe0nkum", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" }, { "id": "Ub437xC2", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Second example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/documents\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/documents');" } ] }, "post": { "summary": "Create Document", "description": "Create a Document. Server-assigned fields are ignored if sent.\n\n**Required scope:** `documents:write`", "operationId": "createDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "author", "parentDocument", "deletedBy", "createdByActor", "updatedByActor", "labels" ] } }, "style": "form", "explode": false, "example": [ "project", "author" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "projectId": "iV6vIU8N", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "accessType": "public", "content": "Looks good — shipping this today.", "locked": false, "archived": false } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentExpanded" }, "examples": { "default": { "value": { "id": "ELe0nkum", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/documents\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"projectId\":\"iV6vIU8N\",\"parentDocumentId\":\"429XYeO6\",\"folderId\":\"dBGa8nam\",\"accessType\":\"public\",\"content\":\"Looks good — shipping this today.\",\"locked\":false,\"archived\":false}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/documents', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"projectId\": \"iV6vIU8N\",\n \"parentDocumentId\": \"429XYeO6\",\n \"folderId\": \"dBGa8nam\",\n \"accessType\": \"public\",\n \"content\": \"Looks good — shipping this today.\",\n \"locked\": false,\n \"archived\": false\n },\n});" } ] } }, "/documents/{id}": { "get": { "summary": "Get Document", "description": "Retrieve a single Document by id.\n\n**Required scope:** `documents:read`", "operationId": "getDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "author", "parentDocument", "deletedBy", "createdByActor", "updatedByActor", "labels" ] } }, "style": "form", "explode": false, "example": [ "project", "author" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentExpanded" }, "examples": { "default": { "value": { "id": "ELe0nkum", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/documents/{id}', {\n params: { path: { id: 'ELe0nkum' } },\n});" } ] }, "patch": { "summary": "Update Document", "description": "Partially update a Document. Only the fields you send are changed.\n\n**Required scope:** `documents:write`", "operationId": "updateDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "author", "parentDocument", "deletedBy", "createdByActor", "updatedByActor", "labels" ] } }, "style": "form", "explode": false, "example": [ "project", "author" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "locked": false, "archived": false, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentExpanded" }, "examples": { "default": { "value": { "id": "ELe0nkum", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"locked\":false,\"archived\":false,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/documents/{id}', {\n params: { path: { id: 'ELe0nkum' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"locked\": false,\n \"archived\": false,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Document", "description": "Move this Document to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `documents:delete`", "operationId": "deleteDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/documents/{id}', {\n params: { path: { id: 'ELe0nkum' } },\n});" } ] } }, "/documents/search": { "get": { "summary": "Search Documents", "description": "Full-text ranked search across documents. Ranked by relevance; pages are capped at 200 results. Filterable by 9 fields.\n\n**Required scope:** `documents:read`", "operationId": "searchDocuments", "tags": [ "document" ], "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "projectId", "in": "query", "required": true, "description": "The project to search within. Required — documents are project-scoped and search has no workspace-wide mode.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "author", "parentDocument", "deletedBy", "createdByActor", "updatedByActor", "labels" ] } }, "style": "form", "explode": false, "example": [ "project", "author" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "parentDocumentId[eq]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` equals.", "schema": { "type": "string" }, "example": "429XYeO6" }, { "name": "parentDocumentId[in]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "429XYeO6", "429XYeO6" ] }, { "name": "parentDocumentId[null]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "parentDocumentId[notNull]", "in": "query", "required": false, "description": "Filter where `parentDocumentId` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "nifty", "google", "dropbox", "microsoft" ] }, "example": "nifty" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "nifty", "google", "dropbox", "microsoft" ] } }, "example": [ "nifty", "google" ] }, { "name": "accessType[eq]", "in": "query", "required": false, "description": "Filter where `accessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited", "private" ] }, "example": "public" }, { "name": "accessType[in]", "in": "query", "required": false, "description": "Filter where `accessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited", "private" ] } }, "example": [ "public", "limited" ] }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "editorVersion[eq]", "in": "query", "required": false, "description": "Filter where `editorVersion` equals.", "schema": { "type": "number" }, "example": 2 }, { "name": "editorVersion[in]", "in": "query", "required": false, "description": "Filter where `editorVersion` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "number" } }, "example": [ 2, 2 ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/documentExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "ELe0nkum", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" }, { "id": "Ub437xC2", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Second example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/documents/search?q=design&projectId=iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/documents/search', {\n params: { query: { q: 'design', projectId: 'iV6vIU8N' } },\n});" } ] } }, "/documents/{id}/labels": { "post": { "summary": "Add labels to a Document", "description": "Link the given ids to this Document as labels. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete labels set afterwards.\n\n**Required scopes:** `documents:write` `documents:link`", "operationId": "addDocumentLabels", "tags": [ "document" ], "x-required-scopes": [ "documents:write", "documents:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Labels to add or remove, by id.", "example": [ "xbUMIqgS", "rXYsOME8" ] } } }, "examples": { "default": { "value": { "ids": [ "xbUMIqgS", "rXYsOME8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The complete labels set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "xbUMIqgS" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } ], "affectedIds": [ "xbUMIqgS" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:write", "documents:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum/labels\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"xbUMIqgS\",\"rXYsOME8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/documents/{id}/labels', {\n params: { path: { id: 'ELe0nkum' } },\n body: {\n \"ids\": [\n \"xbUMIqgS\",\n \"rXYsOME8\"\n ]\n },\n});" } ] } }, "/documents/{id}/labels/remove": { "post": { "summary": "Remove labels from a Document", "description": "Unlink the given ids from this Document's labels. Removing one that is not linked changes nothing. Returns the complete labels set afterwards.\n\n**Required scopes:** `documents:write` `documents:link`", "operationId": "removeDocumentLabels", "tags": [ "document" ], "x-required-scopes": [ "documents:write", "documents:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Labels to add or remove, by id.", "example": [ "xbUMIqgS", "rXYsOME8" ] } } }, "examples": { "default": { "value": { "ids": [ "xbUMIqgS", "rXYsOME8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The complete labels set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "xbUMIqgS" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } ], "affectedIds": [ "xbUMIqgS" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:write", "documents:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum/labels/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"xbUMIqgS\",\"rXYsOME8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/documents/{id}/labels/remove', {\n params: { path: { id: 'ELe0nkum' } },\n body: {\n \"ids\": [\n \"xbUMIqgS\",\n \"rXYsOME8\"\n ]\n },\n});" } ] } }, "/documents/{id}/content": { "get": { "summary": "Content (Document)", "description": "Read a document body as Markdown — the rich-text content, which list and get do not return. Returns { format, content, truncated, byteSize, lossy }; a large body is truncated with truncated=true, and lossy=true means some formatting was dropped in the Markdown conversion.\n\n**Required scope:** `documents:read`", "operationId": "getDocumentContent", "tags": [ "document" ], "x-required-scopes": [ "documents:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "markdown" ] }, "content": { "type": "string" }, "truncated": { "type": "boolean" }, "byteSize": { "type": "number" }, "lossy": { "type": "boolean" } }, "required": [ "format", "content", "truncated", "byteSize", "lossy" ], "additionalProperties": false }, "examples": { "default": { "value": { "format": "markdown", "content": "Looks good — shipping this today.", "truncated": false, "byteSize": 100, "lossy": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum/content\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/documents/{id}/content', {\n params: { path: { id: 'ELe0nkum' } },\n});" } ] } }, "/documents/{id}/append": { "post": { "summary": "Append (Document)", "description": "Append Markdown to the END of a document's body. This is the only way to add to an existing document's content — `update` cannot change the body, and there is no way to replace or delete existing content. Use `content` (the read operation) first if you need to know what the document already says. Appends are additive and never overwrite what is there, including what someone else is typing right now.\n\n**Required scope:** `documents:write`", "operationId": "appendDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "blocksAppended": { "type": "integer", "minimum": 0 }, "byteSize": { "type": "integer", "minimum": 0 }, "sanitized": { "type": "boolean" }, "idempotentReplay": { "type": "boolean" } }, "required": [ "documentId", "blocksAppended", "byteSize", "sanitized", "idempotentReplay" ], "additionalProperties": false }, "examples": { "default": { "value": { "documentId": "ELe0nkum", "blocksAppended": 100, "byteSize": 100, "sanitized": false, "idempotentReplay": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Markdown to append to the END of the document body. Never replaces or deletes existing content. Supports headings, lists, tables, code blocks and Nifty mention syntax. Empty content is an honest no-op: it returns `blocksAppended: 0` and changes nothing, rather than being rejected — so a caller cannot mistake a rejected empty write for a failure." } }, "required": [ "content" ], "additionalProperties": false }, "examples": { "default": { "value": { "content": "Looks good — shipping this today." } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum/append\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"Looks good — shipping this today.\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/documents/{id}/append', {\n params: { path: { id: 'ELe0nkum' } },\n body: {\n \"content\": \"Looks good — shipping this today.\"\n },\n});" } ] } }, "/documents/{id}/edit-text": { "post": { "summary": "Edit text (Document)", "description": "Replace exact text within a document's body — the way to EDIT existing content, as opposed to `append` (which only adds to the end) or `update` (which cannot touch the body at all). Use `content` (the read operation) first to see the exact text to match. By default only the FIRST match of `find` is replaced; use `occurrence` to target the Nth match, `anchorBefore`/`anchorAfter` to disambiguate by surrounding text when `find` is not unique, or `replaceAll` to replace every match. Fails with a teaching error if `find` cannot be located or is ambiguous, rather than guessing. `replace` is inserted as plain text (no Markdown is parsed) and inherits the matched text's formatting.\n\n**Required scope:** `documents:write`", "operationId": "editTextDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "replacements": { "type": "integer", "minimum": 0 }, "byteSize": { "type": "integer", "minimum": 0 }, "idempotentReplay": { "type": "boolean" } }, "required": [ "documentId", "replacements", "byteSize", "idempotentReplay" ], "additionalProperties": false }, "examples": { "default": { "value": { "documentId": "ELe0nkum", "replacements": 100, "byteSize": 100, "idempotentReplay": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Exact text to locate in the document body (read it first with `content` — this must match verbatim, not a pattern). Must be non-empty." }, "replace": { "type": "string", "description": "Text that replaces the located `find` match. May be empty to delete the matched text outright. Plain text only — unlike `append`'s Markdown, no formatting/mentions are interpreted here; the replacement inherits the surrounding text's existing formatting." }, "occurrence": { "type": "integer", "exclusiveMinimum": 0, "description": "When `find` matches more than once, replace only the Nth match (1-based). Omit to target the first match. Ignored when `replaceAll` is true." }, "anchorBefore": { "type": "string", "description": "Disambiguate a non-unique `find` by requiring this exact text to immediately PRECEDE the match. Use when `occurrence` is inconvenient (e.g. the match position may shift)." }, "anchorAfter": { "type": "string", "description": "Disambiguate a non-unique `find` by requiring this exact text to immediately FOLLOW the match. Can be combined with `anchorBefore` to pin both sides of an ambiguous match." }, "replaceAll": { "type": "boolean", "description": "Replace every occurrence of `find` in the document, not just one. When true, `occurrence` is ignored." } }, "required": [ "find", "replace" ], "additionalProperties": false }, "examples": { "default": { "value": { "find": "Example find", "replace": "Example replace", "occurrence": 100, "anchorBefore": "Example anchor before", "anchorAfter": "Example anchor after", "replaceAll": false } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum/edit-text\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"find\":\"Example find\",\"replace\":\"Example replace\",\"occurrence\":100,\"anchorBefore\":\"Example anchor before\",\"anchorAfter\":\"Example anchor after\",\"replaceAll\":false}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/documents/{id}/edit-text', {\n params: { path: { id: 'ELe0nkum' } },\n body: {\n \"find\": \"Example find\",\n \"replace\": \"Example replace\",\n \"occurrence\": 100,\n \"anchorBefore\": \"Example anchor before\",\n \"anchorAfter\": \"Example anchor after\",\n \"replaceAll\": false\n },\n});" } ] } }, "/documents/{id}/restore": { "post": { "summary": "Restore Document", "description": "Restore a Document that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `documents:delete`", "operationId": "restoreDocument", "tags": [ "document" ], "x-required-scopes": [ "documents:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Document.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "ELe0nkum" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/document" }, "examples": { "default": { "value": { "id": "ELe0nkum", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Wfw0dIGm", "name": "Example", "description": "A concise description.", "archived": false, "accessType": "public", "type": "nifty", "subtype": "document", "projectId": "iV6vIU8N", "authorId": "EPmKiCaK", "parentDocumentId": "429XYeO6", "folderId": "dBGa8nam", "locked": false, "externalId": "kdGCOQ47", "externalEmbedUrl": "https://example.com/resource" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "documents:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/documents/ELe0nkum/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/documents/{id}/restore', {\n params: { path: { id: 'ELe0nkum' } },\n});" } ] } }, "/favorites": { "get": { "summary": "List Favorites", "description": "List favorites. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `favorites:read`", "operationId": "listFavorites", "tags": [ "favorite" ], "x-required-scopes": [ "favorites:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "-name", "-order", "-createdAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member", "favoriteFolder", "project" ] } }, "style": "form", "explode": false, "example": [ "member", "favoriteFolder" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "project", "document", "file", "fileFolder", "documentFolder", "projectEmbed", "personalNotes", "personalTasks", "createdByMe" ] }, "example": "project" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "document", "file", "fileFolder", "documentFolder", "projectEmbed", "personalNotes", "personalTasks", "createdByMe" ] } }, "example": [ "project", "document" ] }, { "name": "favoriteFolderId[eq]", "in": "query", "required": false, "description": "Filter where `favoriteFolderId` equals.", "schema": { "type": "string" }, "example": "HXamuWk4" }, { "name": "favoriteFolderId[in]", "in": "query", "required": false, "description": "Filter where `favoriteFolderId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "HXamuWk4", "HXamuWk4" ] }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/favoriteExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "pzw41NKo", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "type": "project", "order": 100, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" }, { "id": "jhEgEEwu", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Second example", "type": "project", "order": 101, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorites:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/favorites\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/favorites');" } ] }, "post": { "summary": "Create Favorite", "description": "Create a Favorite. Server-assigned fields are ignored if sent.\n\n**Required scope:** `favorites:write`", "operationId": "createFavorite", "tags": [ "favorite" ], "x-required-scopes": [ "favorites:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member", "favoriteFolder", "project" ] } }, "style": "form", "explode": false, "example": [ "member", "favoriteFolder" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteCreate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "type": "project", "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteExpanded" }, "examples": { "default": { "value": { "id": "pzw41NKo", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "type": "project", "order": 100, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorites:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/favorites\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"type\":\"project\",\"resourceId\":\"Dd0fq2dw\",\"projectId\":\"iV6vIU8N\",\"favoriteFolderId\":\"HXamuWk4\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/favorites', {\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"type\": \"project\",\n \"resourceId\": \"Dd0fq2dw\",\n \"projectId\": \"iV6vIU8N\",\n \"favoriteFolderId\": \"HXamuWk4\"\n },\n});" } ] } }, "/favorites/{id}": { "get": { "summary": "Get Favorite", "description": "Retrieve a single Favorite by id.\n\n**Required scope:** `favorites:read`", "operationId": "getFavorite", "tags": [ "favorite" ], "x-required-scopes": [ "favorites:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Favorite.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "pzw41NKo" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member", "favoriteFolder", "project" ] } }, "style": "form", "explode": false, "example": [ "member", "favoriteFolder" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteExpanded" }, "examples": { "default": { "value": { "id": "pzw41NKo", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "type": "project", "order": 100, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorites:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/favorites/pzw41NKo\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/favorites/{id}', {\n params: { path: { id: 'pzw41NKo' } },\n});" } ] }, "patch": { "summary": "Update Favorite", "description": "Partially update a Favorite. Only the fields you send are changed.\n\n**Required scope:** `favorites:write`", "operationId": "updateFavorite", "tags": [ "favorite" ], "x-required-scopes": [ "favorites:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Favorite.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "pzw41NKo" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member", "favoriteFolder", "project" ] } }, "style": "form", "explode": false, "example": [ "member", "favoriteFolder" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteUpdate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "favoriteFolderId": "HXamuWk4", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteExpanded" }, "examples": { "default": { "value": { "id": "pzw41NKo", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "type": "project", "order": 100, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorites:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/favorites/pzw41NKo\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"favoriteFolderId\":\"HXamuWk4\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/favorites/{id}', {\n params: { path: { id: 'pzw41NKo' } },\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"favoriteFolderId\": \"HXamuWk4\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Favorite", "description": "Permanently delete this Favorite. This cannot be undone.\n\n**Required scope:** `favorites:delete`", "operationId": "deleteFavorite", "tags": [ "favorite" ], "x-required-scopes": [ "favorites:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Favorite.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "pzw41NKo" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorites:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/favorites/pzw41NKo\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/favorites/{id}', {\n params: { path: { id: 'pzw41NKo' } },\n});" } ] } }, "/favorites/search": { "get": { "summary": "Search Favorites", "description": "Full-text ranked search across favorites. Ranked by relevance; pages are capped at 200 results. Filterable by 4 fields.\n\n**Required scope:** `favorites:read`", "operationId": "searchFavorites", "tags": [ "favorite" ], "x-required-scopes": [ "favorites:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member", "favoriteFolder", "project" ] } }, "style": "form", "explode": false, "example": [ "member", "favoriteFolder" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "project", "document", "file", "fileFolder", "documentFolder", "projectEmbed", "personalNotes", "personalTasks", "createdByMe" ] }, "example": "project" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "document", "file", "fileFolder", "documentFolder", "projectEmbed", "personalNotes", "personalTasks", "createdByMe" ] } }, "example": [ "project", "document" ] }, { "name": "favoriteFolderId[eq]", "in": "query", "required": false, "description": "Filter where `favoriteFolderId` equals.", "schema": { "type": "string" }, "example": "HXamuWk4" }, { "name": "favoriteFolderId[in]", "in": "query", "required": false, "description": "Filter where `favoriteFolderId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "HXamuWk4", "HXamuWk4" ] }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/favoriteExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "pzw41NKo", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "type": "project", "order": 100, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" }, { "id": "jhEgEEwu", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Second example", "type": "project", "order": 101, "resourceId": "Dd0fq2dw", "projectId": "iV6vIU8N", "favoriteFolderId": "HXamuWk4", "memberId": "P3hYIKqK" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorites:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/favorites/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/favorites/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/favorite-folders": { "get": { "summary": "List Favorite Folders", "description": "List favoriteFolders. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 2 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `favorite-folders:read`", "operationId": "listFavoriteFolders", "tags": [ "favoriteFolder" ], "x-required-scopes": [ "favorite-folders:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "-name", "-order", "-createdAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdBy", "updatedBy" ] } }, "style": "form", "explode": false, "example": [ "createdBy", "updatedBy" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/favoriteFolderExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "HXamuWk4", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "order": 100, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" }, { "id": "AFK6t4p6", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Second example", "order": 101, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorite-folders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/favorite-folders\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/favorite-folders');" } ] }, "post": { "summary": "Create Favorite Folder", "description": "Create a Favorite Folder. Server-assigned fields are ignored if sent.\n\n**Required scope:** `favorite-folders:write`", "operationId": "createFavoriteFolder", "tags": [ "favoriteFolder" ], "x-required-scopes": [ "favorite-folders:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdBy", "updatedBy" ] } }, "style": "form", "explode": false, "example": [ "createdBy", "updatedBy" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteFolderCreate" }, "examples": { "default": { "value": { "name": "Example", "order": 100 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteFolderExpanded" }, "examples": { "default": { "value": { "id": "HXamuWk4", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "order": 100, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorite-folders:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/favorite-folders\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/favorite-folders', {\n body: {\n \"name\": \"Example\",\n \"order\": 100\n },\n});" } ] } }, "/favorite-folders/{id}": { "get": { "summary": "Get Favorite Folder", "description": "Retrieve a single Favorite Folder by id.\n\n**Required scope:** `favorite-folders:read`", "operationId": "getFavoriteFolder", "tags": [ "favoriteFolder" ], "x-required-scopes": [ "favorite-folders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Favorite Folder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "HXamuWk4" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdBy", "updatedBy" ] } }, "style": "form", "explode": false, "example": [ "createdBy", "updatedBy" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteFolderExpanded" }, "examples": { "default": { "value": { "id": "HXamuWk4", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "order": 100, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorite-folders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/favorite-folders/HXamuWk4\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/favorite-folders/{id}', {\n params: { path: { id: 'HXamuWk4' } },\n});" } ] }, "patch": { "summary": "Update Favorite Folder", "description": "Partially update a Favorite Folder. Only the fields you send are changed.\n\n**Required scope:** `favorite-folders:write`", "operationId": "updateFavoriteFolder", "tags": [ "favoriteFolder" ], "x-required-scopes": [ "favorite-folders:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Favorite Folder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "HXamuWk4" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdBy", "updatedBy" ] } }, "style": "form", "explode": false, "example": [ "createdBy", "updatedBy" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteFolderUpdate" }, "examples": { "default": { "value": { "name": "Example", "order": 100, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/favoriteFolderExpanded" }, "examples": { "default": { "value": { "id": "HXamuWk4", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "order": 100, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorite-folders:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/favorite-folders/HXamuWk4\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":100,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/favorite-folders/{id}', {\n params: { path: { id: 'HXamuWk4' } },\n body: {\n \"name\": \"Example\",\n \"order\": 100,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Favorite Folder", "description": "Permanently delete this Favorite Folder. This cannot be undone.\n\n**Required scope:** `favorite-folders:delete`", "operationId": "deleteFavoriteFolder", "tags": [ "favoriteFolder" ], "x-required-scopes": [ "favorite-folders:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Favorite Folder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "HXamuWk4" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorite-folders:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/favorite-folders/HXamuWk4\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/favorite-folders/{id}', {\n params: { path: { id: 'HXamuWk4' } },\n});" } ] } }, "/favorite-folders/search": { "get": { "summary": "Search Favorite Folders", "description": "Full-text ranked search across favoriteFolders. Ranked by relevance; pages are capped at 200 results. Filterable by 2 fields.\n\n**Required scope:** `favorite-folders:read`", "operationId": "searchFavoriteFolders", "tags": [ "favoriteFolder" ], "x-required-scopes": [ "favorite-folders:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdBy", "updatedBy" ] } }, "style": "form", "explode": false, "example": [ "createdBy", "updatedBy" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/favoriteFolderExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "HXamuWk4", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Example", "order": 100, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" }, { "id": "AFK6t4p6", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "name": "Second example", "order": 101, "createdById": "EfcGKsYk", "updatedById": "ZJIkEsGm" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "favorite-folders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/favorite-folders/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/favorite-folders/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/files": { "get": { "summary": "List Files", "description": "List files. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 12 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `files:read`", "operationId": "listFiles", "tags": [ "file" ], "x-required-scopes": [ "files:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`.", "schema": { "type": "string", "enum": [ "name", "size", "createdAt", "updatedAt", "projectId", "taskId", "folderId", "messageId", "-name", "-size", "-createdAt", "-updatedAt", "-projectId", "-taskId", "-folderId", "-messageId" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "uploader", "deletedBy", "createdByActor", "updatedByActor", "project", "task", "document", "message", "annotationTask", "subscribers", "labels", "annotations" ] } }, "style": "form", "explode": false, "example": [ "uploader", "deletedBy" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "documentId[eq]", "in": "query", "required": false, "description": "Filter where `documentId` equals.", "schema": { "type": "string" }, "example": "ELe0nkum" }, { "name": "documentId[in]", "in": "query", "required": false, "description": "Filter where `documentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ELe0nkum", "ELe0nkum" ] }, { "name": "messageId[eq]", "in": "query", "required": false, "description": "Filter where `messageId` equals.", "schema": { "type": "string" }, "example": "4SsY67bC" }, { "name": "messageId[in]", "in": "query", "required": false, "description": "Filter where `messageId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "4SsY67bC", "4SsY67bC" ] }, { "name": "folderId[eq]", "in": "query", "required": false, "description": "Filter where `folderId` equals.", "schema": { "type": "string" }, "example": "dBGa8nam" }, { "name": "folderId[in]", "in": "query", "required": false, "description": "Filter where `folderId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "dBGa8nam", "dBGa8nam" ] }, { "name": "annotationTaskId[eq]", "in": "query", "required": false, "description": "Filter where `annotationTaskId` equals.", "schema": { "type": "string" }, "example": "fV4pUGI6" }, { "name": "annotationTaskId[in]", "in": "query", "required": false, "description": "Filter where `annotationTaskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "fV4pUGI6", "fV4pUGI6" ] }, { "name": "uploaderId[eq]", "in": "query", "required": false, "description": "Filter where `uploaderId` equals.", "schema": { "type": "string" }, "example": "FL6HICQe" }, { "name": "uploaderId[in]", "in": "query", "required": false, "description": "Filter where `uploaderId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "FL6HICQe", "FL6HICQe" ] }, { "name": "processed[eq]", "in": "query", "required": false, "description": "Filter where `processed` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/fileExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "xvM2toUM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" }, { "id": "xvQmW0l0", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Second example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/files\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/files');" } ] }, "post": { "summary": "Create File", "description": "Create a File. Server-assigned fields are ignored if sent. This REGISTERS METADATA — it does not upload bytes. Get the bytes into storage first with the createUploadUrl operation (which returns an `uploadKey` plus a presigned URL to PUT to), then create the file passing that `uploadKey`, the `name` and the `size` in bytes. createFromContent and uploadFromUrl do both halves in one call. AT LEAST ONE parent is required: `projectId`, `taskId`, `documentId`, `messageId` or `folderId` — a create with none of them is rejected. A file is capped at 2 GB, and each team has a total storage quota; exceeding either is rejected.\n\n**Required scope:** `files:write`", "operationId": "createFile", "tags": [ "file" ], "x-required-scopes": [ "files:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "uploader", "deletedBy", "createdByActor", "updatedByActor", "project", "task", "document", "message", "annotationTask", "subscribers", "labels", "annotations" ] } }, "style": "form", "explode": false, "example": [ "uploader", "deletedBy" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fileCreate" }, "examples": { "default": { "value": { "name": "Example", "size": 20480, "uploadKey": "Example upload key", "projectId": "iV6vIU8N" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fileExpanded" }, "examples": { "default": { "value": { "id": "xvM2toUM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"size\":20480,\"uploadKey\":\"Example upload key\",\"projectId\":\"iV6vIU8N\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files', {\n body: {\n \"name\": \"Example\",\n \"size\": 20480,\n \"uploadKey\": \"Example upload key\",\n \"projectId\": \"iV6vIU8N\"\n },\n});" } ] } }, "/files/{id}": { "get": { "summary": "Get File", "description": "Retrieve a single File by id.\n\n**Required scope:** `files:read`", "operationId": "getFile", "tags": [ "file" ], "x-required-scopes": [ "files:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "uploader", "deletedBy", "createdByActor", "updatedByActor", "project", "task", "document", "message", "annotationTask", "subscribers", "labels", "annotations" ] } }, "style": "form", "explode": false, "example": [ "uploader", "deletedBy" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fileExpanded" }, "examples": { "default": { "value": { "id": "xvM2toUM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/files/xvM2toUM\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/files/{id}', {\n params: { path: { id: 'xvM2toUM' } },\n});" } ] }, "patch": { "summary": "Update File", "description": "Partially update a File. Only the fields you send are changed.\n\n**Required scope:** `files:write`", "operationId": "updateFile", "tags": [ "file" ], "x-required-scopes": [ "files:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "uploader", "deletedBy", "createdByActor", "updatedByActor", "project", "task", "document", "message", "annotationTask", "subscribers", "labels", "annotations" ] } }, "style": "form", "explode": false, "example": [ "uploader", "deletedBy" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fileUpdate" }, "examples": { "default": { "value": { "name": "Example", "size": 20480, "folderId": "dBGa8nam", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fileExpanded" }, "examples": { "default": { "value": { "id": "xvM2toUM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/files/xvM2toUM\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"size\":20480,\"folderId\":\"dBGa8nam\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/files/{id}', {\n params: { path: { id: 'xvM2toUM' } },\n body: {\n \"name\": \"Example\",\n \"size\": 20480,\n \"folderId\": \"dBGa8nam\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete File", "description": "Move this File to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `files:delete`", "operationId": "deleteFile", "tags": [ "file" ], "x-required-scopes": [ "files:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/files/xvM2toUM\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/files/{id}', {\n params: { path: { id: 'xvM2toUM' } },\n});" } ] } }, "/files/search": { "get": { "summary": "Search Files", "description": "Full-text ranked search across files. Ranked by relevance; pages are capped at 200 results. Filterable by 12 fields.\n\n**Required scope:** `files:read`", "operationId": "searchFiles", "tags": [ "file" ], "x-required-scopes": [ "files:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "uploader", "deletedBy", "createdByActor", "updatedByActor", "project", "task", "document", "message", "annotationTask", "subscribers", "labels", "annotations" ] } }, "style": "form", "explode": false, "example": [ "uploader", "deletedBy" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "documentId[eq]", "in": "query", "required": false, "description": "Filter where `documentId` equals.", "schema": { "type": "string" }, "example": "ELe0nkum" }, { "name": "documentId[in]", "in": "query", "required": false, "description": "Filter where `documentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ELe0nkum", "ELe0nkum" ] }, { "name": "messageId[eq]", "in": "query", "required": false, "description": "Filter where `messageId` equals.", "schema": { "type": "string" }, "example": "4SsY67bC" }, { "name": "messageId[in]", "in": "query", "required": false, "description": "Filter where `messageId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "4SsY67bC", "4SsY67bC" ] }, { "name": "folderId[eq]", "in": "query", "required": false, "description": "Filter where `folderId` equals.", "schema": { "type": "string" }, "example": "dBGa8nam" }, { "name": "folderId[in]", "in": "query", "required": false, "description": "Filter where `folderId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "dBGa8nam", "dBGa8nam" ] }, { "name": "annotationTaskId[eq]", "in": "query", "required": false, "description": "Filter where `annotationTaskId` equals.", "schema": { "type": "string" }, "example": "fV4pUGI6" }, { "name": "annotationTaskId[in]", "in": "query", "required": false, "description": "Filter where `annotationTaskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "fV4pUGI6", "fV4pUGI6" ] }, { "name": "uploaderId[eq]", "in": "query", "required": false, "description": "Filter where `uploaderId` equals.", "schema": { "type": "string" }, "example": "FL6HICQe" }, { "name": "uploaderId[in]", "in": "query", "required": false, "description": "Filter where `uploaderId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "FL6HICQe", "FL6HICQe" ] }, { "name": "processed[eq]", "in": "query", "required": false, "description": "Filter where `processed` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/fileExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "xvM2toUM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" }, { "id": "xvQmW0l0", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Second example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/files/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/files/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/files/{id}/subscribers": { "post": { "summary": "Add subscribers to a File", "description": "Link the given ids to this File as subscribers. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete subscribers set afterwards.\n\n**Required scopes:** `files:write` `files:link`", "operationId": "addFileSubscribers", "tags": [ "file" ], "x-required-scopes": [ "files:write", "files:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete subscribers set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write", "files:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/xvM2toUM/subscribers\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/{id}/subscribers', {\n params: { path: { id: 'xvM2toUM' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/files/{id}/subscribers/remove": { "post": { "summary": "Remove subscribers from a File", "description": "Unlink the given ids from this File's subscribers. Removing one that is not linked changes nothing. Returns the complete subscribers set afterwards.\n\n**Required scopes:** `files:write` `files:link`", "operationId": "removeFileSubscribers", "tags": [ "file" ], "x-required-scopes": [ "files:write", "files:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete subscribers set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write", "files:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/xvM2toUM/subscribers/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/{id}/subscribers/remove', {\n params: { path: { id: 'xvM2toUM' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/files/{id}/labels": { "post": { "summary": "Add labels to a File", "description": "Link the given ids to this File as labels. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete labels set afterwards.\n\n**Required scopes:** `files:write` `files:link`", "operationId": "addFileLabels", "tags": [ "file" ], "x-required-scopes": [ "files:write", "files:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Labels to add or remove, by id.", "example": [ "xbUMIqgS", "rXYsOME8" ] } } }, "examples": { "default": { "value": { "ids": [ "xbUMIqgS", "rXYsOME8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The complete labels set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "xbUMIqgS" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } ], "affectedIds": [ "xbUMIqgS" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write", "files:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/xvM2toUM/labels\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"xbUMIqgS\",\"rXYsOME8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/{id}/labels', {\n params: { path: { id: 'xvM2toUM' } },\n body: {\n \"ids\": [\n \"xbUMIqgS\",\n \"rXYsOME8\"\n ]\n },\n});" } ] } }, "/files/{id}/labels/remove": { "post": { "summary": "Remove labels from a File", "description": "Unlink the given ids from this File's labels. Removing one that is not linked changes nothing. Returns the complete labels set afterwards.\n\n**Required scopes:** `files:write` `files:link`", "operationId": "removeFileLabels", "tags": [ "file" ], "x-required-scopes": [ "files:write", "files:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Labels to add or remove, by id.", "example": [ "xbUMIqgS", "rXYsOME8" ] } } }, "examples": { "default": { "value": { "ids": [ "xbUMIqgS", "rXYsOME8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The complete labels set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "xbUMIqgS" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } ], "affectedIds": [ "xbUMIqgS" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write", "files:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/xvM2toUM/labels/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"xbUMIqgS\",\"rXYsOME8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/{id}/labels/remove', {\n params: { path: { id: 'xvM2toUM' } },\n body: {\n \"ids\": [\n \"xbUMIqgS\",\n \"rXYsOME8\"\n ]\n },\n});" } ] } }, "/files/create-upload-url": { "post": { "summary": "Create upload url (File)", "description": "Mint a presigned S3 upload URL — step 1 of uploading a new file. Step 2: HTTP PUT the raw bytes to `uploadUrl` sending exactly `headers`. Step 3: create the file with `POST /files`, passing the returned `uploadKey`, plus name, size (byte count of what you uploaded), and exactly ONE parent — projectId, taskId, documentId or messageId. uploadUrl expires (~15 min); max 2 GB. If your client cannot make raw HTTP PUTs (sandboxed environments), use createFromContent instead (max 3 MB). To attach an asset you only have a URL for, use uploadFromUrl instead (max 25 MB).\n\n**Required scope:** `files:write`", "operationId": "createUploadUrlFiles", "tags": [ "file" ], "x-required-scopes": [ "files:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadKey": { "type": "string", "description": "Pass this VERBATIM as `uploadKey` when creating the file row." }, "uploadUrl": { "type": "string", "description": "Presigned S3 URL — HTTP PUT the raw file bytes here." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Send exactly these headers on the PUT." }, "expiresAt": { "type": "string", "description": "ISO timestamp when uploadUrl stops working." } }, "required": [ "uploadKey", "uploadUrl", "headers", "expiresAt" ], "additionalProperties": false }, "examples": { "default": { "value": { "uploadKey": "Example upload key", "uploadUrl": "https://example.com/resource", "headers": {}, "expiresAt": "2026-06-04T11:00:00.000Z" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name WITH extension — used to derive content type and the stored object name." }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "IANA media type to store. Omit and the server infers it — for uploadFromUrl from the fetched response Content-Type, otherwise from the content prefix or the name extension." } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "default": { "value": { "name": "Example", "contentType": "Example content type" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/create-upload-url\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"contentType\":\"Example content type\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/create-upload-url', {\n body: {\n \"name\": \"Example\",\n \"contentType\": \"Example content type\"\n },\n});" } ] } }, "/files/create-from-content": { "post": { "summary": "Create from content (File)", "description": "Create a file from inline base64 content in ONE call — for clients that cannot HTTP PUT raw bytes to S3 (sandboxed/egress-blocked environments); max 3 MB decoded. Prefer createUploadUrl + HTTP PUT when your environment has open egress — base64 costs ~1.37x the bytes and transits your context. `name` needs the file extension. Pass at least one parent — taskId, projectId, documentId, messageId or folderId; with only taskId the server derives the project from the task. If you only have a URL to the asset, use uploadFromUrl.\n\n**Required scope:** `files:write`", "operationId": "createFromContentFiles", "tags": [ "file" ], "x-required-scopes": [ "files:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the created file row." }, "name": { "type": "string", "description": "Stored file name (echoes what you sent)." }, "size": { "type": "number", "description": "Decoded byte count of the stored object (server-computed)." }, "url": { "type": [ "string", "null" ], "description": "Presigned download URL for the stored object (null only if presigning failed — the file still exists)." }, "idempotentReplay": { "type": "boolean", "description": "True when this call replayed an earlier identical one; nothing was uploaded this time." } }, "required": [ "id", "name", "size", "url", "idempotentReplay" ], "additionalProperties": false }, "examples": { "default": { "value": { "id": "XXKmAKg6", "name": "Example", "size": 100, "url": "https://example.com/resource", "idempotentReplay": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name WITH extension — the extension drives content-type inference and the stored object name." }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 4300000, "description": "File bytes as base64 (standard or url-safe alphabet; an optional `data:;base64,` prefix is accepted). Max 3 MB decoded." }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "IANA media type of the bytes. Omit to infer from a `data:` URI prefix or the name extension." }, "projectId": { "type": "string", "minLength": 1, "description": "Attach the file to this project." }, "taskId": { "type": "string", "minLength": 1, "description": "Attach the file to this task (the project is derived from it)." }, "documentId": { "type": "string", "minLength": 1, "description": "Attach the file to this document." }, "messageId": { "type": "string", "minLength": 1, "description": "Attach the file to this message." }, "folderId": { "type": "string", "minLength": 1, "description": "Place the file in this folder." } }, "required": [ "name", "contentBase64" ], "additionalProperties": false }, "examples": { "default": { "value": { "name": "Example", "contentBase64": "Example content base64", "contentType": "Example content type", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/create-from-content\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"contentBase64\":\"Example content base64\",\"contentType\":\"Example content type\",\"projectId\":\"iV6vIU8N\",\"taskId\":\"KfS0ha8P\",\"documentId\":\"ELe0nkum\",\"messageId\":\"4SsY67bC\",\"folderId\":\"dBGa8nam\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/create-from-content', {\n body: {\n \"name\": \"Example\",\n \"contentBase64\": \"Example content base64\",\n \"contentType\": \"Example content type\",\n \"projectId\": \"iV6vIU8N\",\n \"taskId\": \"KfS0ha8P\",\n \"documentId\": \"ELe0nkum\",\n \"messageId\": \"4SsY67bC\",\n \"folderId\": \"dBGa8nam\"\n },\n});" } ] } }, "/files/upload-from-url": { "post": { "summary": "Upload from url (File)", "description": "Create a file from a public http/https URL in ONE call — the SERVER fetches it, for a client that has the address but cannot fetch the bytes (egress-blocked/sandboxed environments); the URL goes in `sourceUrl` (not `uploadKey`, which on file create is the pointer to already-uploaded bytes, and not `url`, which is the download link on a stored file), max 25 MB, and at least one parent is required (taskId, projectId, documentId, messageId or folderId). Up to 3 redirects; private/internal addresses are refused. `name` defaults to the URL's filename. With only taskId the server derives projectId. If you HAVE the bytes and they are ≤3 MB use createFromContent; for big files with open egress use createUploadUrl + HTTP PUT.\n\n**Required scope:** `files:write`", "operationId": "uploadFromUrlFiles", "tags": [ "file" ], "x-required-scopes": [ "files:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the created file row." }, "name": { "type": "string", "description": "Stored file name (what you sent, or the name derived from the URL)." }, "size": { "type": "number", "description": "Byte count of the fetched object as stored (server-computed)." }, "url": { "type": [ "string", "null" ], "description": "Presigned download URL for the stored object (null only if presigning failed — the file still exists)." }, "idempotentReplay": { "type": "boolean", "description": "True when this call replayed an earlier identical one; nothing was fetched or stored this time." } }, "required": [ "id", "name", "size", "url", "idempotentReplay" ], "additionalProperties": false }, "examples": { "default": { "value": { "id": "XXKmAKg6", "name": "Example", "size": 100, "url": "https://example.com/resource", "idempotentReplay": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceUrl": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Public http/https URL the SERVER fetches the bytes from. Up to 3 redirects are followed (every hop is re-validated); max 25 MB; default ports only. URLs with embedded credentials are refused, as are private/internal addresses." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name WITH extension. Omit to use the basename of the final URL path (after redirects)." }, "contentType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "IANA media type to store, overriding the response Content-Type. Omit to use that header, then the name extension, then application/octet-stream." }, "projectId": { "type": "string", "minLength": 1, "description": "Attach the file to this project." }, "taskId": { "type": "string", "minLength": 1, "description": "Attach the file to this task (the project is derived from it)." }, "documentId": { "type": "string", "minLength": 1, "description": "Attach the file to this document." }, "messageId": { "type": "string", "minLength": 1, "description": "Attach the file to this message." }, "folderId": { "type": "string", "minLength": 1, "description": "Place the file in this folder." } }, "required": [ "sourceUrl" ], "additionalProperties": false }, "examples": { "default": { "value": { "sourceUrl": "https://example.com/resource", "name": "Example", "contentType": "Example content type", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/upload-from-url\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"sourceUrl\":\"https://example.com/resource\",\"name\":\"Example\",\"contentType\":\"Example content type\",\"projectId\":\"iV6vIU8N\",\"taskId\":\"KfS0ha8P\",\"documentId\":\"ELe0nkum\",\"messageId\":\"4SsY67bC\",\"folderId\":\"dBGa8nam\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/upload-from-url', {\n body: {\n \"sourceUrl\": \"https://example.com/resource\",\n \"name\": \"Example\",\n \"contentType\": \"Example content type\",\n \"projectId\": \"iV6vIU8N\",\n \"taskId\": \"KfS0ha8P\",\n \"documentId\": \"ELe0nkum\",\n \"messageId\": \"4SsY67bC\",\n \"folderId\": \"dBGa8nam\"\n },\n});" } ] } }, "/files/{id}/restore": { "post": { "summary": "Restore File", "description": "Restore a File that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `files:delete`", "operationId": "restoreFile", "tags": [ "file" ], "x-required-scopes": [ "files:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the File.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xvM2toUM" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/file" }, "examples": { "default": { "value": { "id": "xvM2toUM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "1IYoWAgA", "name": "Example", "size": 20480, "url": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "processed": false, "download": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "thumbnail": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "folderStack": [ "BJemkA8N" ], "subscribers": [], "labels": [], "uploaderId": "FL6HICQe", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "messageId": "4SsY67bC", "folderId": "dBGa8nam", "annotationTaskId": "fV4pUGI6" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "files:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/files/xvM2toUM/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/files/{id}/restore', {\n params: { path: { id: 'xvM2toUM' } },\n});" } ] } }, "/forms": { "get": { "summary": "List Forms", "description": "List forms. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `forms:read`", "operationId": "listForms", "tags": [ "form" ], "x-required-scopes": [ "forms:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "createdAt", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "createdByActor", "updatedByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "project", "createdByActor" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "automation[eq]", "in": "query", "required": false, "description": "Filter where `automation` equals.", "schema": { "type": "string", "enum": [ "task", "doc", "message", "checkin" ] }, "example": "task" }, { "name": "automation[in]", "in": "query", "required": false, "description": "Filter where `automation` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "doc", "message", "checkin" ] } }, "example": [ "task", "doc" ] }, { "name": "docAccessType[eq]", "in": "query", "required": false, "description": "Filter where `docAccessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited", "private" ] }, "example": "public" }, { "name": "docAccessType[in]", "in": "query", "required": false, "description": "Filter where `docAccessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited", "private" ] } }, "example": [ "public", "limited" ] }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "createdById[eq]", "in": "query", "required": false, "description": "Filter where `createdById` equals.", "schema": { "type": "string" }, "example": "Qf8HggwY" }, { "name": "createdById[in]", "in": "query", "required": false, "description": "Filter where `createdById` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Qf8HggwY", "Qf8HggwY" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/formExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "Jt0ByAIi", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Xv6FM6n4", "name": "Example", "automation": "task", "targetStatusId": "00taIogS", "targetListId": "s7BA8vsY", "meta": {}, "success": {}, "multiSubmit": false, "docAccessType": "public", "url": "https://example.com/resource", "projectId": "iV6vIU8N", "createdById": "Qf8HggwY", "fields": [] }, { "id": "dbkMyiYA", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Xv6FM6n4", "name": "Second example", "automation": "task", "targetStatusId": "00taIogS", "targetListId": "s7BA8vsY", "meta": {}, "success": {}, "multiSubmit": false, "docAccessType": "public", "url": "https://example.com/resource", "projectId": "iV6vIU8N", "createdById": "Qf8HggwY", "fields": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "forms:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/forms\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/forms');" } ] } }, "/forms/{id}": { "get": { "summary": "Get Form", "description": "Retrieve a single Form by id.\n\n**Required scope:** `forms:read`", "operationId": "getForm", "tags": [ "form" ], "x-required-scopes": [ "forms:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Form.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Jt0ByAIi" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "createdByActor", "updatedByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "project", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/formExpanded" }, "examples": { "default": { "value": { "id": "Jt0ByAIi", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Xv6FM6n4", "name": "Example", "automation": "task", "targetStatusId": "00taIogS", "targetListId": "s7BA8vsY", "meta": {}, "success": {}, "multiSubmit": false, "docAccessType": "public", "url": "https://example.com/resource", "projectId": "iV6vIU8N", "createdById": "Qf8HggwY", "fields": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "forms:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/forms/Jt0ByAIi\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/forms/{id}', {\n params: { path: { id: 'Jt0ByAIi' } },\n});" } ] } }, "/forms/{id}/restore": { "post": { "summary": "Restore Form", "description": "Restore a Form that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `forms:delete`", "operationId": "restoreForm", "tags": [ "form" ], "x-required-scopes": [ "forms:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Form.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Jt0ByAIi" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/form" }, "examples": { "default": { "value": { "id": "Jt0ByAIi", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Xv6FM6n4", "name": "Example", "automation": "task", "targetStatusId": "00taIogS", "targetListId": "s7BA8vsY", "meta": {}, "success": {}, "multiSubmit": false, "docAccessType": "public", "url": "https://example.com/resource", "projectId": "iV6vIU8N", "createdById": "Qf8HggwY", "fields": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "forms:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/forms/Jt0ByAIi/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/forms/{id}/restore', {\n params: { path: { id: 'Jt0ByAIi' } },\n});" } ] } }, "/goals": { "get": { "summary": "List Goals", "description": "List goals. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `goals:read`", "operationId": "listGoals", "tags": [ "goal" ], "x-required-scopes": [ "goals:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "name", "endAt", "createdAt", "-name", "-endAt", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "goalGroup", "members", "tasks", "lists", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "owner", "goalGroup" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "accessType[eq]", "in": "query", "required": false, "description": "Filter where `accessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited", "private" ] }, "example": "public" }, { "name": "accessType[in]", "in": "query", "required": false, "description": "Filter where `accessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited", "private" ] } }, "example": [ "public", "limited" ] }, { "name": "goalGroupId[eq]", "in": "query", "required": false, "description": "Filter where `goalGroupId` equals.", "schema": { "type": "string" }, "example": "pPAcKseY" }, { "name": "goalGroupId[in]", "in": "query", "required": false, "description": "Filter where `goalGroupId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "pPAcKseY", "pPAcKseY" ] }, { "name": "ownerId[eq]", "in": "query", "required": false, "description": "Filter where `ownerId` equals.", "schema": { "type": "string" }, "example": "QpCuKyI2" }, { "name": "ownerId[in]", "in": "query", "required": false, "description": "Filter where `ownerId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "QpCuKyI2", "QpCuKyI2" ] }, { "name": "endAt[eq]", "in": "query", "required": false, "description": "Filter where `endAt` equals.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[gt]", "in": "query", "required": false, "description": "Filter where `endAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[gte]", "in": "query", "required": false, "description": "Filter where `endAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[lt]", "in": "query", "required": false, "description": "Filter where `endAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[lte]", "in": "query", "required": false, "description": "Filter where `endAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/goalExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" }, { "id": "MP8tuQuA", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goals:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/goals\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/goals');" } ] }, "post": { "summary": "Create Goal", "description": "Create a Goal. Server-assigned fields are ignored if sent. Requires a human-backed identity — a user session or a personal access token. Application and agent tokens receive 403 here; they can read goals but not change them.\n\n**Required scope:** `goals:write`", "operationId": "createGoal", "tags": [ "goal" ], "x-required-scopes": [ "goals:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "goalGroup", "members", "tasks", "lists", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "owner", "goalGroup" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "accessType": "public", "endAt": "2026-06-14T12:00:00.000Z", "goalGroupId": "pPAcKseY", "members": [ "P3hYIKqK" ], "goalSourceType": "customField", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "tasks": [ "KfS0ha8P" ], "lists": [ "lN6ZQycO" ], "trackMetricType": "taskCount", "trackMetricValue": "Example track metric value", "targetType": "dynamic", "targetValue": 100, "ownerId": "QpCuKyI2" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalExpanded" }, "examples": { "default": { "value": { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goals:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/goals\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"accessType\":\"public\",\"endAt\":\"2026-06-14T12:00:00.000Z\",\"goalGroupId\":\"pPAcKseY\",\"members\":[\"P3hYIKqK\"],\"goalSourceType\":\"customField\",\"goalSourceValue\":\"Example goal source value\",\"goalSourceOption\":\"Example goal source option\",\"tasks\":[\"KfS0ha8P\"],\"lists\":[\"lN6ZQycO\"],\"trackMetricType\":\"taskCount\",\"trackMetricValue\":\"Example track metric value\",\"targetType\":\"dynamic\",\"targetValue\":100,\"ownerId\":\"QpCuKyI2\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/goals', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"accessType\": \"public\",\n \"endAt\": \"2026-06-14T12:00:00.000Z\",\n \"goalGroupId\": \"pPAcKseY\",\n \"members\": [\n \"P3hYIKqK\"\n ],\n \"goalSourceType\": \"customField\",\n \"goalSourceValue\": \"Example goal source value\",\n \"goalSourceOption\": \"Example goal source option\",\n \"tasks\": [\n \"KfS0ha8P\"\n ],\n \"lists\": [\n \"lN6ZQycO\"\n ],\n \"trackMetricType\": \"taskCount\",\n \"trackMetricValue\": \"Example track metric value\",\n \"targetType\": \"dynamic\",\n \"targetValue\": 100,\n \"ownerId\": \"QpCuKyI2\"\n },\n});" } ] } }, "/goals/{id}": { "get": { "summary": "Get Goal", "description": "Retrieve a single Goal by id.\n\n**Required scope:** `goals:read`", "operationId": "getGoal", "tags": [ "goal" ], "x-required-scopes": [ "goals:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Goal.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "AdESgais" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "goalGroup", "members", "tasks", "lists", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "owner", "goalGroup" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalExpanded" }, "examples": { "default": { "value": { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goals:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/goals/AdESgais\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/goals/{id}', {\n params: { path: { id: 'AdESgais' } },\n});" } ] }, "patch": { "summary": "Update Goal", "description": "Partially update a Goal. Only the fields you send are changed. Requires a human-backed identity — a user session or a personal access token. Application and agent tokens receive 403 here; they can read goals but not change them.\n\n**Required scope:** `goals:write`", "operationId": "updateGoal", "tags": [ "goal" ], "x-required-scopes": [ "goals:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Goal.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "AdESgais" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "goalGroup", "members", "tasks", "lists", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "owner", "goalGroup" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "accessType": "public", "endAt": "2026-06-14T12:00:00.000Z", "goalGroupId": "pPAcKseY", "goalSourceType": "customField", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricType": "taskCount", "trackMetricValue": "Example track metric value", "targetType": "dynamic", "targetValue": 100, "ownerId": "QpCuKyI2", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalExpanded" }, "examples": { "default": { "value": { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goals:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/goals/AdESgais\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"accessType\":\"public\",\"endAt\":\"2026-06-14T12:00:00.000Z\",\"goalGroupId\":\"pPAcKseY\",\"goalSourceType\":\"customField\",\"goalSourceValue\":\"Example goal source value\",\"goalSourceOption\":\"Example goal source option\",\"trackMetricType\":\"taskCount\",\"trackMetricValue\":\"Example track metric value\",\"targetType\":\"dynamic\",\"targetValue\":100,\"ownerId\":\"QpCuKyI2\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/goals/{id}', {\n params: { path: { id: 'AdESgais' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"accessType\": \"public\",\n \"endAt\": \"2026-06-14T12:00:00.000Z\",\n \"goalGroupId\": \"pPAcKseY\",\n \"goalSourceType\": \"customField\",\n \"goalSourceValue\": \"Example goal source value\",\n \"goalSourceOption\": \"Example goal source option\",\n \"trackMetricType\": \"taskCount\",\n \"trackMetricValue\": \"Example track metric value\",\n \"targetType\": \"dynamic\",\n \"targetValue\": 100,\n \"ownerId\": \"QpCuKyI2\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Goal", "description": "Permanently delete this Goal. This cannot be undone. Requires a human-backed identity — a user session or a personal access token. Application and agent tokens receive 403 here; they can read goals but not change them.\n\n**Required scope:** `goals:delete`", "operationId": "deleteGoal", "tags": [ "goal" ], "x-required-scopes": [ "goals:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Goal.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "AdESgais" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goals:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/goals/AdESgais\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/goals/{id}', {\n params: { path: { id: 'AdESgais' } },\n});" } ] } }, "/goals/search": { "get": { "summary": "Search Goals", "description": "Full-text ranked search across goals. Ranked by relevance; pages are capped at 200 results. Filterable by 6 fields.\n\n**Required scope:** `goals:read`", "operationId": "searchGoals", "tags": [ "goal" ], "x-required-scopes": [ "goals:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "goalGroup", "members", "tasks", "lists", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "owner", "goalGroup" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "accessType[eq]", "in": "query", "required": false, "description": "Filter where `accessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited", "private" ] }, "example": "public" }, { "name": "accessType[in]", "in": "query", "required": false, "description": "Filter where `accessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited", "private" ] } }, "example": [ "public", "limited" ] }, { "name": "goalGroupId[eq]", "in": "query", "required": false, "description": "Filter where `goalGroupId` equals.", "schema": { "type": "string" }, "example": "pPAcKseY" }, { "name": "goalGroupId[in]", "in": "query", "required": false, "description": "Filter where `goalGroupId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "pPAcKseY", "pPAcKseY" ] }, { "name": "ownerId[eq]", "in": "query", "required": false, "description": "Filter where `ownerId` equals.", "schema": { "type": "string" }, "example": "QpCuKyI2" }, { "name": "ownerId[in]", "in": "query", "required": false, "description": "Filter where `ownerId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "QpCuKyI2", "QpCuKyI2" ] }, { "name": "endAt[eq]", "in": "query", "required": false, "description": "Filter where `endAt` equals.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[gt]", "in": "query", "required": false, "description": "Filter where `endAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[gte]", "in": "query", "required": false, "description": "Filter where `endAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[lt]", "in": "query", "required": false, "description": "Filter where `endAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "endAt[lte]", "in": "query", "required": false, "description": "Filter where `endAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/goalExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" }, { "id": "MP8tuQuA", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goals:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/goals/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/goals/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/goal-groups": { "get": { "summary": "List Goal Groups", "description": "List goalGroups. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 2 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `goal-groups:read`", "operationId": "listGoalGroups", "tags": [ "goalGroup" ], "x-required-scopes": [ "goal-groups:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "goals", "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "goals", "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/goalGroupExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "pPAcKseY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description." }, { "id": "DL21BIcS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "description": "A concise description." } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goal-groups:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/goal-groups\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/goal-groups');" } ] }, "post": { "summary": "Create Goal Group", "description": "Create a Goal Group. Server-assigned fields are ignored if sent.\n\n**Required scope:** `goal-groups:write`", "operationId": "createGoalGroup", "tags": [ "goalGroup" ], "x-required-scopes": [ "goal-groups:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "goals", "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "goals", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalGroupCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalGroupExpanded" }, "examples": { "default": { "value": { "id": "pPAcKseY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description." } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goal-groups:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/goal-groups\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/goal-groups', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\"\n },\n});" } ] } }, "/goal-groups/{id}": { "get": { "summary": "Get Goal Group", "description": "Retrieve a single Goal Group by id.\n\n**Required scope:** `goal-groups:read`", "operationId": "getGoalGroup", "tags": [ "goalGroup" ], "x-required-scopes": [ "goal-groups:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Goal Group.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "pPAcKseY" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "goals", "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "goals", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalGroupExpanded" }, "examples": { "default": { "value": { "id": "pPAcKseY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description." } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goal-groups:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/goal-groups/pPAcKseY\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/goal-groups/{id}', {\n params: { path: { id: 'pPAcKseY' } },\n});" } ] }, "patch": { "summary": "Update Goal Group", "description": "Partially update a Goal Group. Only the fields you send are changed.\n\n**Required scope:** `goal-groups:write`", "operationId": "updateGoalGroup", "tags": [ "goalGroup" ], "x-required-scopes": [ "goal-groups:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Goal Group.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "pPAcKseY" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "goals", "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "goals", "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalGroupUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goalGroupExpanded" }, "examples": { "default": { "value": { "id": "pPAcKseY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description." } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goal-groups:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/goal-groups/pPAcKseY\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/goal-groups/{id}', {\n params: { path: { id: 'pPAcKseY' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Goal Group", "description": "Permanently delete this Goal Group. This cannot be undone. The goals in the group are NOT deleted: every one of them survives with `goalGroupId` set to null.\n\n**Required scope:** `goal-groups:delete`", "operationId": "deleteGoalGroup", "tags": [ "goalGroup" ], "x-required-scopes": [ "goal-groups:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Goal Group.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "pPAcKseY" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goal-groups:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/goal-groups/pPAcKseY\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/goal-groups/{id}', {\n params: { path: { id: 'pPAcKseY' } },\n});" } ] } }, "/goal-groups/search": { "get": { "summary": "Search Goal Groups", "description": "Full-text ranked search across goalGroups. Ranked by relevance; pages are capped at 200 results. Filterable by 2 fields.\n\n**Required scope:** `goal-groups:read`", "operationId": "searchGoalGroups", "tags": [ "goalGroup" ], "x-required-scopes": [ "goal-groups:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "goals", "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "goals", "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/goalGroupExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "pPAcKseY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description." }, { "id": "DL21BIcS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "description": "A concise description." } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "goal-groups:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/goal-groups/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/goal-groups/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/labels": { "get": { "summary": "List Labels", "description": "List labels. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `labels:read`", "operationId": "listLabels", "tags": [ "label" ], "x-required-scopes": [ "labels:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "deletedBy" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "color[eq]", "in": "query", "required": false, "description": "Filter where `color` equals.", "schema": { "type": "string" }, "example": "#00A99B" }, { "name": "color[in]", "in": "query", "required": false, "description": "Filter where `color` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "#00A99B", "#00A99B" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "others", "member" ] }, "example": "others" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "others", "member" ] } }, "example": [ "others", "member" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/labelExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" }, { "id": "dfwACsYG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Second example", "color": "#00A99B", "default": false, "type": "others" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/labels\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/labels');" } ] }, "post": { "summary": "Create Label", "description": "Create a Label. Server-assigned fields are ignored if sent. Send at least one of `name` or `color`; an empty body is rejected. Label names are unique per workspace among live labels, so reusing one returns 409.\n\n**Required scope:** `labels:write`", "operationId": "createLabel", "tags": [ "label" ], "x-required-scopes": [ "labels:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "deletedBy" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/labelCreate" }, "examples": { "default": { "value": { "name": "Example", "type": "others" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/labelExpanded" }, "examples": { "default": { "value": { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/labels\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"type\":\"others\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/labels', {\n body: {\n \"name\": \"Example\",\n \"type\": \"others\"\n },\n});" } ] } }, "/labels/{id}": { "get": { "summary": "Get Label", "description": "Retrieve a single Label by id.\n\n**Required scope:** `labels:read`", "operationId": "getLabel", "tags": [ "label" ], "x-required-scopes": [ "labels:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Label.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xbUMIqgS" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "deletedBy" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/labelExpanded" }, "examples": { "default": { "value": { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/labels/xbUMIqgS\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/labels/{id}', {\n params: { path: { id: 'xbUMIqgS' } },\n});" } ] }, "patch": { "summary": "Update Label", "description": "Partially update a Label. Only the fields you send are changed.\n\n**Required scope:** `labels:write`", "operationId": "updateLabel", "tags": [ "label" ], "x-required-scopes": [ "labels:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Label.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xbUMIqgS" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "deletedBy" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/labelUpdate" }, "examples": { "default": { "value": { "name": "Example", "color": "#00A99B", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/labelExpanded" }, "examples": { "default": { "value": { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/labels/xbUMIqgS\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"color\":\"#00A99B\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/labels/{id}', {\n params: { path: { id: 'xbUMIqgS' } },\n body: {\n \"name\": \"Example\",\n \"color\": \"#00A99B\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Label", "description": "Move this Label to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `labels:delete`", "operationId": "deleteLabel", "tags": [ "label" ], "x-required-scopes": [ "labels:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Label.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xbUMIqgS" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/labels/xbUMIqgS\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/labels/{id}', {\n params: { path: { id: 'xbUMIqgS' } },\n});" } ] } }, "/labels/search": { "get": { "summary": "Search Labels", "description": "Full-text ranked search across labels. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.\n\n**Required scope:** `labels:read`", "operationId": "searchLabels", "tags": [ "label" ], "x-required-scopes": [ "labels:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "deletedBy" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "deletedBy" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "color[eq]", "in": "query", "required": false, "description": "Filter where `color` equals.", "schema": { "type": "string" }, "example": "#00A99B" }, { "name": "color[in]", "in": "query", "required": false, "description": "Filter where `color` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "#00A99B", "#00A99B" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "others", "member" ] }, "example": "others" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "others", "member" ] } }, "example": [ "others", "member" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/labelExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" }, { "id": "dfwACsYG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Second example", "color": "#00A99B", "default": false, "type": "others" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/labels/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/labels/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/labels/{id}/restore": { "post": { "summary": "Restore Label", "description": "Restore a Label that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `labels:delete`", "operationId": "restoreLabel", "tags": [ "label" ], "x-required-scopes": [ "labels:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Label.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "xbUMIqgS" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/label" }, "examples": { "default": { "value": { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "labels:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/labels/xbUMIqgS/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/labels/{id}/restore', {\n params: { path: { id: 'xbUMIqgS' } },\n});" } ] } }, "/lists": { "get": { "summary": "List Lists", "description": "List lists. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 11 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `lists:read`", "operationId": "listLists", "tags": [ "list" ], "x-required-scopes": [ "lists:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list lists across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "start", "end", "order", "createdAt", "updatedAt", "-name", "-start", "-end", "-order", "-createdAt", "-updatedAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "project", "dependency", "recurringRule", "status", "assignees", "hiddenFor", "goals", "customFields", "tasks" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "isMilestone[eq]", "in": "query", "required": false, "description": "Filter where `isMilestone` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "dependencyId[eq]", "in": "query", "required": false, "description": "Filter where `dependencyId` equals.", "schema": { "type": "string" }, "example": "i9TUmOWm" }, { "name": "dependencyId[in]", "in": "query", "required": false, "description": "Filter where `dependencyId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "i9TUmOWm", "i9TUmOWm" ] }, { "name": "statusId[eq]", "in": "query", "required": false, "description": "Filter where `statusId` equals.", "schema": { "type": "string" }, "example": "5aM4ncwI" }, { "name": "statusId[in]", "in": "query", "required": false, "description": "Filter where `statusId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "5aM4ncwI", "5aM4ncwI" ] }, { "name": "ruleId[eq]", "in": "query", "required": false, "description": "Filter where `ruleId` equals.", "schema": { "type": "string" }, "example": "J55f2zQ2" }, { "name": "ruleId[in]", "in": "query", "required": false, "description": "Filter where `ruleId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "J55f2zQ2", "J55f2zQ2" ] }, { "name": "start[gt]", "in": "query", "required": false, "description": "Filter where `start` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[gte]", "in": "query", "required": false, "description": "Filter where `start` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lt]", "in": "query", "required": false, "description": "Filter where `start` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lte]", "in": "query", "required": false, "description": "Filter where `start` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "end[gt]", "in": "query", "required": false, "description": "Filter where `end` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "end[gte]", "in": "query", "required": false, "description": "Filter where `end` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "end[lt]", "in": "query", "required": false, "description": "Filter where `end` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "end[lte]", "in": "query", "required": false, "description": "Filter where `end` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/listExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "lN6ZQycO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" }, { "id": "96zA0TKS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Second example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 101, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/lists\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/lists');" } ] }, "post": { "summary": "Create List", "description": "Create a List. Server-assigned fields are ignored if sent.\n\n**Required scope:** `lists:write`", "operationId": "createList", "tags": [ "list" ], "x-required-scopes": [ "lists:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "project", "dependency", "recurringRule", "status", "assignees", "hiddenFor", "goals", "customFields", "tasks" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "archived": false, "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI", "assignees": [ "CNIgSuay" ], "hiddenFor": [ "eN87BSak" ], "goals": [ "AdESgais" ], "customFields": [] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listExpanded" }, "examples": { "default": { "value": { "id": "lN6ZQycO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"start\":\"2026-06-01T12:00:00.000Z\",\"end\":\"2026-06-14T12:00:00.000Z\",\"order\":100,\"color\":\"#00A99B\",\"archived\":false,\"isMilestone\":false,\"projectId\":\"iV6vIU8N\",\"dependencyId\":\"i9TUmOWm\",\"statusId\":\"5aM4ncwI\",\"assignees\":[\"CNIgSuay\"],\"hiddenFor\":[\"eN87BSak\"],\"goals\":[\"AdESgais\"],\"customFields\":[]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"start\": \"2026-06-01T12:00:00.000Z\",\n \"end\": \"2026-06-14T12:00:00.000Z\",\n \"order\": 100,\n \"color\": \"#00A99B\",\n \"archived\": false,\n \"isMilestone\": false,\n \"projectId\": \"iV6vIU8N\",\n \"dependencyId\": \"i9TUmOWm\",\n \"statusId\": \"5aM4ncwI\",\n \"assignees\": [\n \"CNIgSuay\"\n ],\n \"hiddenFor\": [\n \"eN87BSak\"\n ],\n \"goals\": [\n \"AdESgais\"\n ],\n \"customFields\": []\n },\n});" } ] } }, "/lists/{id}": { "get": { "summary": "Get List", "description": "Retrieve a single List by id.\n\n**Required scope:** `lists:read`", "operationId": "getList", "tags": [ "list" ], "x-required-scopes": [ "lists:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "project", "dependency", "recurringRule", "status", "assignees", "hiddenFor", "goals", "customFields", "tasks" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listExpanded" }, "examples": { "default": { "value": { "id": "lN6ZQycO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/lists/{id}', {\n params: { path: { id: 'lN6ZQycO' } },\n});" } ] }, "patch": { "summary": "Update List", "description": "Partially update a List. Only the fields you send are changed.\n\n**Required scope:** `lists:write`", "operationId": "updateList", "tags": [ "list" ], "x-required-scopes": [ "lists:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "project", "dependency", "recurringRule", "status", "assignees", "hiddenFor", "goals", "customFields", "tasks" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "archived": false, "isMilestone": false, "dependencyId": "i9TUmOWm", "assignees": [ "CNIgSuay" ], "hiddenFor": [ "eN87BSak" ], "goals": [ "AdESgais" ], "customFields": [], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listExpanded" }, "examples": { "default": { "value": { "id": "lN6ZQycO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"start\":\"2026-06-01T12:00:00.000Z\",\"end\":\"2026-06-14T12:00:00.000Z\",\"order\":100,\"color\":\"#00A99B\",\"archived\":false,\"isMilestone\":false,\"dependencyId\":\"i9TUmOWm\",\"assignees\":[\"CNIgSuay\"],\"hiddenFor\":[\"eN87BSak\"],\"goals\":[\"AdESgais\"],\"customFields\":[],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/lists/{id}', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"start\": \"2026-06-01T12:00:00.000Z\",\n \"end\": \"2026-06-14T12:00:00.000Z\",\n \"order\": 100,\n \"color\": \"#00A99B\",\n \"archived\": false,\n \"isMilestone\": false,\n \"dependencyId\": \"i9TUmOWm\",\n \"assignees\": [\n \"CNIgSuay\"\n ],\n \"hiddenFor\": [\n \"eN87BSak\"\n ],\n \"goals\": [\n \"AdESgais\"\n ],\n \"customFields\": [],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete List", "description": "Permanently delete this List. This cannot be undone.\n\n**Required scope:** `lists:delete`", "operationId": "deleteList", "tags": [ "list" ], "x-required-scopes": [ "lists:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/lists/{id}', {\n params: { path: { id: 'lN6ZQycO' } },\n});" } ] } }, "/lists/search": { "get": { "summary": "Search Lists", "description": "Full-text ranked search across lists. Ranked by relevance; pages are capped at 200 results. Filterable by 11 fields.\n\n**Required scope:** `lists:read`", "operationId": "searchLists", "tags": [ "list" ], "x-required-scopes": [ "lists:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "projectId", "in": "query", "required": true, "description": "The project to search within. Required — lists are project-scoped and search has no workspace-wide mode.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "project", "dependency", "recurringRule", "status", "assignees", "hiddenFor", "goals", "customFields", "tasks" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "isMilestone[eq]", "in": "query", "required": false, "description": "Filter where `isMilestone` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "dependencyId[eq]", "in": "query", "required": false, "description": "Filter where `dependencyId` equals.", "schema": { "type": "string" }, "example": "i9TUmOWm" }, { "name": "dependencyId[in]", "in": "query", "required": false, "description": "Filter where `dependencyId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "i9TUmOWm", "i9TUmOWm" ] }, { "name": "statusId[eq]", "in": "query", "required": false, "description": "Filter where `statusId` equals.", "schema": { "type": "string" }, "example": "5aM4ncwI" }, { "name": "statusId[in]", "in": "query", "required": false, "description": "Filter where `statusId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "5aM4ncwI", "5aM4ncwI" ] }, { "name": "ruleId[eq]", "in": "query", "required": false, "description": "Filter where `ruleId` equals.", "schema": { "type": "string" }, "example": "J55f2zQ2" }, { "name": "ruleId[in]", "in": "query", "required": false, "description": "Filter where `ruleId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "J55f2zQ2", "J55f2zQ2" ] }, { "name": "start[gt]", "in": "query", "required": false, "description": "Filter where `start` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[gte]", "in": "query", "required": false, "description": "Filter where `start` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lt]", "in": "query", "required": false, "description": "Filter where `start` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lte]", "in": "query", "required": false, "description": "Filter where `start` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "end[gt]", "in": "query", "required": false, "description": "Filter where `end` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "end[gte]", "in": "query", "required": false, "description": "Filter where `end` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "end[lt]", "in": "query", "required": false, "description": "Filter where `end` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "end[lte]", "in": "query", "required": false, "description": "Filter where `end` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-14T12:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/listExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "lN6ZQycO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 100, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" }, { "id": "96zA0TKS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "name": "Second example", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "order": 101, "color": "#00A99B", "isMilestone": false, "projectId": "iV6vIU8N", "dependencyId": "i9TUmOWm", "statusId": "5aM4ncwI" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/lists/search?q=design&projectId=iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/lists/search', {\n params: { query: { q: 'design', projectId: 'iV6vIU8N' } },\n});" } ] } }, "/lists/{id}/assignees": { "post": { "summary": "Add assignees to a List", "description": "Link the given ids to this List as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `lists:write` `lists:link`", "operationId": "addListAssignees", "tags": [ "list" ], "x-required-scopes": [ "lists:write", "lists:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write", "lists:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO/assignees\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists/{id}/assignees', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/lists/{id}/assignees/remove": { "post": { "summary": "Remove assignees from a List", "description": "Unlink the given ids from this List's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `lists:write` `lists:link`", "operationId": "removeListAssignees", "tags": [ "list" ], "x-required-scopes": [ "lists:write", "lists:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write", "lists:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO/assignees/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists/{id}/assignees/remove', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/lists/{id}/hidden-for": { "post": { "summary": "Add hidden for to a List", "description": "Link the given ids to this List as hiddenFor. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete hiddenFor set afterwards.\n\n**Required scopes:** `lists:write` `lists:link`", "operationId": "addListHiddenFor", "tags": [ "list" ], "x-required-scopes": [ "lists:write", "lists:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Roles to add or remove, by id.", "example": [ "zngY4nUy", "50hcKom2" ] } } }, "examples": { "default": { "value": { "ids": [ "zngY4nUy", "50hcKom2" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The complete hiddenFor set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "zngY4nUy" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "affectedIds": [ "zngY4nUy" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write", "lists:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO/hidden-for\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"zngY4nUy\",\"50hcKom2\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists/{id}/hidden-for', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"ids\": [\n \"zngY4nUy\",\n \"50hcKom2\"\n ]\n },\n});" } ] } }, "/lists/{id}/hidden-for/remove": { "post": { "summary": "Remove hidden for from a List", "description": "Unlink the given ids from this List's hiddenFor. Removing one that is not linked changes nothing. Returns the complete hiddenFor set afterwards.\n\n**Required scopes:** `lists:write` `lists:link`", "operationId": "removeListHiddenFor", "tags": [ "list" ], "x-required-scopes": [ "lists:write", "lists:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Roles to add or remove, by id.", "example": [ "zngY4nUy", "50hcKom2" ] } } }, "examples": { "default": { "value": { "ids": [ "zngY4nUy", "50hcKom2" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The complete hiddenFor set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "zngY4nUy" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "affectedIds": [ "zngY4nUy" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write", "lists:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO/hidden-for/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"zngY4nUy\",\"50hcKom2\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists/{id}/hidden-for/remove', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"ids\": [\n \"zngY4nUy\",\n \"50hcKom2\"\n ]\n },\n});" } ] } }, "/lists/{id}/goals": { "post": { "summary": "Add goals to a List", "description": "Link the given ids to this List as goals. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete goals set afterwards.\n\n**Required scopes:** `lists:write` `lists:link`", "operationId": "addListGoals", "tags": [ "list" ], "x-required-scopes": [ "lists:write", "lists:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Goals to add or remove, by id.", "example": [ "AdESgais", "ij4ZIqgm" ] } } }, "examples": { "default": { "value": { "ids": [ "AdESgais", "ij4ZIqgm" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/goal" }, "description": "The complete goals set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "AdESgais" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } ], "affectedIds": [ "AdESgais" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write", "lists:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO/goals\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"AdESgais\",\"ij4ZIqgm\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists/{id}/goals', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"ids\": [\n \"AdESgais\",\n \"ij4ZIqgm\"\n ]\n },\n});" } ] } }, "/lists/{id}/goals/remove": { "post": { "summary": "Remove goals from a List", "description": "Unlink the given ids from this List's goals. Removing one that is not linked changes nothing. Returns the complete goals set afterwards.\n\n**Required scopes:** `lists:write` `lists:link`", "operationId": "removeListGoals", "tags": [ "list" ], "x-required-scopes": [ "lists:write", "lists:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the List.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "lN6ZQycO" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Goals to add or remove, by id.", "example": [ "AdESgais", "ij4ZIqgm" ] } } }, "examples": { "default": { "value": { "ids": [ "AdESgais", "ij4ZIqgm" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/goal" }, "description": "The complete goals set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "AdESgais" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "AdESgais", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "description": "A concise description.", "accessType": "public", "goalSourceType": "customField", "trackMetricType": "taskCount", "targetType": "dynamic", "goalSourceValue": "Example goal source value", "goalSourceOption": "Example goal source option", "trackMetricValue": "Example track metric value", "targetValue": 100, "progressTotal": 100, "progressCompleted": 100, "endAt": "2026-06-14T12:00:00.000Z", "completedAt": "2026-06-03T12:00:00.000Z", "teamId": "cfC83TeS", "ownerId": "QpCuKyI2", "goalGroupId": "pPAcKseY" } ], "affectedIds": [ "AdESgais" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "lists:write", "lists:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/lists/lN6ZQycO/goals/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"AdESgais\",\"ij4ZIqgm\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/lists/{id}/goals/remove', {\n params: { path: { id: 'lN6ZQycO' } },\n body: {\n \"ids\": [\n \"AdESgais\",\n \"ij4ZIqgm\"\n ]\n },\n});" } ] } }, "/members": { "get": { "summary": "List Team Members", "description": "List members. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `name` unless you pass `sort`.\n\n**Required scope:** `members:read`", "operationId": "listMembers", "tags": [ "member" ], "x-required-scopes": [ "members:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `name`.", "schema": { "type": "string", "enum": [ "name", "email", "-name", "-email" ] }, "example": "name" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "customFields" ] } }, "style": "form", "explode": false, "example": [ "customFields" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "email[eq]", "in": "query", "required": false, "description": "Filter where `email` equals.", "schema": { "type": "string", "format": "email" }, "example": "jane@acme.com" }, { "name": "email[contains]", "in": "query", "required": false, "description": "Filter where `email` contains.", "schema": { "type": "string", "format": "email" }, "example": "jane@acme.com" }, { "name": "online[eq]", "in": "query", "required": false, "description": "Filter where `online` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "pending[eq]", "in": "query", "required": false, "description": "Filter where `pending` equals.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/memberExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 }, { "id": "V5pwKAam", "userId": "EF6LMc0F", "name": "Second example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "members:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/members\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/members');" } ] }, "post": { "summary": "Create Team Member", "description": "Create a Team Member. Server-assigned fields are ignored if sent. Creating a member is an invitation. It emails the address you supply, consumes a seat (a team at its plan limit gets 409), and needs the `inviteToTeam` permission — plus `inviteToProject` if you pass `projectId`. It is idempotent on an email that is already active (you get the existing member back), it reactivates a previously removed member rather than creating a second one, and it cannot invite someone as `owner`. Only `email`, `name`, `roleId` and `projectId` are read; everything else on the member is either set by the person themselves or derived.\n\n**Required scope:** `members:write`", "operationId": "createMember", "tags": [ "member" ], "x-required-scopes": [ "members:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "customFields" ] } }, "style": "form", "explode": false, "example": [ "customFields" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberCreate" }, "examples": { "default": { "value": { "email": "jane@acme.com", "name": "Example", "roleId": "zngY4nUy", "projectId": "iV6vIU8N" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberExpanded" }, "examples": { "default": { "value": { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "members:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/members\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\":\"jane@acme.com\",\"name\":\"Example\",\"roleId\":\"zngY4nUy\",\"projectId\":\"iV6vIU8N\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/members', {\n body: {\n \"email\": \"jane@acme.com\",\n \"name\": \"Example\",\n \"roleId\": \"zngY4nUy\",\n \"projectId\": \"iV6vIU8N\"\n },\n});" } ] } }, "/members/{id}": { "get": { "summary": "Get Team Member", "description": "Retrieve a single Team Member by id.\n\n**Required scope:** `members:read`", "operationId": "getMember", "tags": [ "member" ], "x-required-scopes": [ "members:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Team Member.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "P3hYIKqK" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "customFields" ] } }, "style": "form", "explode": false, "example": [ "customFields" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberExpanded" }, "examples": { "default": { "value": { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "members:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/members/P3hYIKqK\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/members/{id}', {\n params: { path: { id: 'P3hYIKqK' } },\n});" } ] }, "patch": { "summary": "Update Team Member", "description": "Partially update a Team Member. Only the fields you send are changed.\n\n**Required scope:** `members:write`", "operationId": "updateMember", "tags": [ "member" ], "x-required-scopes": [ "members:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Team Member.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "P3hYIKqK" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "customFields" ] } }, "style": "form", "explode": false, "example": [ "customFields" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberUpdate" }, "examples": { "default": { "value": { "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100, "customFields": [] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/memberExpanded" }, "examples": { "default": { "value": { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "members:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/members/P3hYIKqK\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"roleId\":\"zngY4nUy\",\"theme\":\"light\",\"storyPointsCapacity\":100,\"customFields\":[]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/members/{id}', {\n params: { path: { id: 'P3hYIKqK' } },\n body: {\n \"roleId\": \"zngY4nUy\",\n \"theme\": \"light\",\n \"storyPointsCapacity\": 100,\n \"customFields\": []\n },\n});" } ] }, "delete": { "summary": "Delete Team Member", "description": "Deactivate this Team Member. It stops appearing in list results but the record is preserved and can be restored. This removes the person from the team and cascades: their task, list and status assignments are handed to the team owner, their chat and document memberships are dropped, their notifications are purged and their tokens are revoked. It requires `removeFromTeam`, and the team owner cannot be removed. Restoring the member restores the membership only — reassigned tasks, dropped chat and document memberships, and revoked tokens all stay as the removal left them.\n\n**Required scope:** `members:delete`", "operationId": "deleteMember", "tags": [ "member" ], "x-required-scopes": [ "members:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Team Member.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "P3hYIKqK" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "members:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/members/P3hYIKqK\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/members/{id}', {\n params: { path: { id: 'P3hYIKqK' } },\n});" } ] } }, "/members/{id}/restore": { "post": { "summary": "Restore Team Member", "description": "Restore a Team Member that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `members:delete`", "operationId": "restoreMember", "tags": [ "member" ], "x-required-scopes": [ "members:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Team Member.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "P3hYIKqK" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/member" }, "examples": { "default": { "value": { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "members:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/members/P3hYIKqK/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/members/{id}/restore', {\n params: { path: { id: 'P3hYIKqK' } },\n});" } ] } }, "/messages": { "get": { "summary": "List Messages", "description": "List messages. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 14 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `messages:read`", "operationId": "listMessages", "tags": [ "message" ], "x-required-scopes": [ "messages:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`.", "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "-createdAt", "-updatedAt" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "deletedBy", "createdByActor", "updatedByActor", "chat", "task", "document", "file", "annotation", "parentMessage", "sharedDocument", "tagged", "seenBy", "hiddenFor", "files", "replies" ] } }, "style": "form", "explode": false, "example": [ "author", "deletedBy" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "authorId[eq]", "in": "query", "required": false, "description": "Filter where `authorId` equals.", "schema": { "type": "string" }, "example": "EPmKiCaK" }, { "name": "authorId[in]", "in": "query", "required": false, "description": "Filter where `authorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "EPmKiCaK", "EPmKiCaK" ] }, { "name": "chatId[eq]", "in": "query", "required": false, "description": "Filter where `chatId` equals.", "schema": { "type": "string" }, "example": "hTIeouEK" }, { "name": "chatId[in]", "in": "query", "required": false, "description": "Filter where `chatId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "hTIeouEK", "hTIeouEK" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "documentId[eq]", "in": "query", "required": false, "description": "Filter where `documentId` equals.", "schema": { "type": "string" }, "example": "ELe0nkum" }, { "name": "documentId[in]", "in": "query", "required": false, "description": "Filter where `documentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ELe0nkum", "ELe0nkum" ] }, { "name": "fileId[eq]", "in": "query", "required": false, "description": "Filter where `fileId` equals.", "schema": { "type": "string" }, "example": "xvM2toUM" }, { "name": "fileId[in]", "in": "query", "required": false, "description": "Filter where `fileId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "xvM2toUM", "xvM2toUM" ] }, { "name": "annotationId[eq]", "in": "query", "required": false, "description": "Filter where `annotationId` equals.", "schema": { "type": "string" }, "example": "863BiyIc" }, { "name": "annotationId[in]", "in": "query", "required": false, "description": "Filter where `annotationId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "863BiyIc", "863BiyIc" ] }, { "name": "parentMessageId[eq]", "in": "query", "required": false, "description": "Filter where `parentMessageId` equals.", "schema": { "type": "string" }, "example": "gx21BskY" }, { "name": "parentMessageId[in]", "in": "query", "required": false, "description": "Filter where `parentMessageId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "gx21BskY", "gx21BskY" ] }, { "name": "sharedDocumentId[eq]", "in": "query", "required": false, "description": "Filter where `sharedDocumentId` equals.", "schema": { "type": "string" }, "example": "vjciEwQy" }, { "name": "sharedDocumentId[in]", "in": "query", "required": false, "description": "Filter where `sharedDocumentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "vjciEwQy", "vjciEwQy" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "text", "gif", "document", "audio" ] }, "example": "text" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "gif", "document", "audio" ] } }, "example": [ "text", "gif" ] }, { "name": "subtype[eq]", "in": "query", "required": false, "description": "Filter where `subtype` equals.", "schema": { "type": "string", "enum": [ "hello", "joinProject", "joinChat", "createTask", "archiveTask", "unarchiveTask", "addTaskDeadline", "removeTaskDeadline", "completeTask", "moveTask", "moveSubtask", "convertToTask", "untieTask", "tieTask", "assignTask", "unassignTask", "moveProject", "meetingStart", "meetingEnd", "mentionTaskInCommit", "mentionTaskInPR", "addTaskStartDate", "removeTaskStartDate", "sendMessage", "unCompleteTask", "enableRecurringOnTask", "taskAddLabel", "taskRemoveLabel", "taskAddAssignee", "taskRemoveAssignee", "taskAddGoal", "taskRemoveGoal", "taskUpdateDependency", "taskUpdateField", "taskUpdateReminder", "taskUpdateStoryPoints", "timeEntryCreate", "taskOverdue", "taskAddChecklist", "taskRemoveChecklist", "taskUpdateChecklist", "taskAddChecklistItem", "taskRemoveChecklistItem", "taskUpdateChecklistItem", "taskCompleteChecklistItem", "taskUncompleteChecklistItem", "taskAddLabeledAssignee", "taskRemoveLabeledAssignee", "timeEntryEdited", "timeEntryRemoved", "taskAddSubscriber", "taskRemoveSubscriber" ] }, "example": "hello" }, { "name": "subtype[in]", "in": "query", "required": false, "description": "Filter where `subtype` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "hello", "joinProject", "joinChat", "createTask", "archiveTask", "unarchiveTask", "addTaskDeadline", "removeTaskDeadline", "completeTask", "moveTask", "moveSubtask", "convertToTask", "untieTask", "tieTask", "assignTask", "unassignTask", "moveProject", "meetingStart", "meetingEnd", "mentionTaskInCommit", "mentionTaskInPR", "addTaskStartDate", "removeTaskStartDate", "sendMessage", "unCompleteTask", "enableRecurringOnTask", "taskAddLabel", "taskRemoveLabel", "taskAddAssignee", "taskRemoveAssignee", "taskAddGoal", "taskRemoveGoal", "taskUpdateDependency", "taskUpdateField", "taskUpdateReminder", "taskUpdateStoryPoints", "timeEntryCreate", "taskOverdue", "taskAddChecklist", "taskRemoveChecklist", "taskUpdateChecklist", "taskAddChecklistItem", "taskRemoveChecklistItem", "taskUpdateChecklistItem", "taskCompleteChecklistItem", "taskUncompleteChecklistItem", "taskAddLabeledAssignee", "taskRemoveLabeledAssignee", "timeEntryEdited", "timeEntryRemoved", "taskAddSubscriber", "taskRemoveSubscriber" ] } }, "example": [ "hello", "joinProject" ] }, { "name": "subtype[null]", "in": "query", "required": false, "description": "Filter where `subtype` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "subtype[notNull]", "in": "query", "required": false, "description": "Filter where `subtype` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "isEdited[eq]", "in": "query", "required": false, "description": "Filter where `isEdited` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/messageExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "4SsY67bC", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] }, { "id": "yNKAKwWM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/messages\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/messages');" } ] }, "post": { "summary": "Create Message", "description": "Create a Message. Server-assigned fields are ignored if sent.\n\n**Required scope:** `messages:write`", "operationId": "createMessage", "tags": [ "message" ], "x-required-scopes": [ "messages:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "deletedBy", "createdByActor", "updatedByActor", "chat", "task", "document", "file", "annotation", "parentMessage", "sharedDocument", "tagged", "seenBy", "hiddenFor", "files", "replies" ] } }, "style": "form", "explode": false, "example": [ "author", "deletedBy" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/messageCreate" }, "examples": { "default": { "value": { "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "hideLinkPreview": false, "audioDuration": 100, "chatId": "hTIeouEK", "tagged": [ "lnQ0jGkG" ], "files": [ "xvM2toUM" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/messageCreated" }, "examples": { "default": { "value": { "id": "4SsY67bC", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ], "created": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/messages\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\":\"Looks good — shipping this today.\",\"url\":\"https://example.com/resource\",\"type\":\"text\",\"hideLinkPreview\":false,\"audioDuration\":100,\"chatId\":\"hTIeouEK\",\"tagged\":[\"lnQ0jGkG\"],\"files\":[\"xvM2toUM\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/messages', {\n body: {\n \"text\": \"Looks good — shipping this today.\",\n \"url\": \"https://example.com/resource\",\n \"type\": \"text\",\n \"hideLinkPreview\": false,\n \"audioDuration\": 100,\n \"chatId\": \"hTIeouEK\",\n \"tagged\": [\n \"lnQ0jGkG\"\n ],\n \"files\": [\n \"xvM2toUM\"\n ]\n },\n});" } ] } }, "/messages/{id}": { "get": { "summary": "Get Message", "description": "Retrieve a single Message by id.\n\n**Required scope:** `messages:read`", "operationId": "getMessage", "tags": [ "message" ], "x-required-scopes": [ "messages:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Message.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "4SsY67bC" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "deletedBy", "createdByActor", "updatedByActor", "chat", "task", "document", "file", "annotation", "parentMessage", "sharedDocument", "tagged", "seenBy", "hiddenFor", "files", "replies" ] } }, "style": "form", "explode": false, "example": [ "author", "deletedBy" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/messageExpanded" }, "examples": { "default": { "value": { "id": "4SsY67bC", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/messages/4SsY67bC\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/messages/{id}', {\n params: { path: { id: '4SsY67bC' } },\n});" } ] }, "patch": { "summary": "Update Message", "description": "Partially update a Message. Only the fields you send are changed.\n\n**Required scope:** `messages:write`", "operationId": "updateMessage", "tags": [ "message" ], "x-required-scopes": [ "messages:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Message.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "4SsY67bC" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "deletedBy", "createdByActor", "updatedByActor", "chat", "task", "document", "file", "annotation", "parentMessage", "sharedDocument", "tagged", "seenBy", "hiddenFor", "files", "replies" ] } }, "style": "form", "explode": false, "example": [ "author", "deletedBy" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/messageUpdate" }, "examples": { "default": { "value": { "text": "Looks good — shipping this today.", "hideLinkPreview": false, "files": [ "xvM2toUM" ], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/messageExpanded" }, "examples": { "default": { "value": { "id": "4SsY67bC", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/messages/4SsY67bC\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\":\"Looks good — shipping this today.\",\"hideLinkPreview\":false,\"files\":[\"xvM2toUM\"],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/messages/{id}', {\n params: { path: { id: '4SsY67bC' } },\n body: {\n \"text\": \"Looks good — shipping this today.\",\n \"hideLinkPreview\": false,\n \"files\": [\n \"xvM2toUM\"\n ],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Message", "description": "Move this Message to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `messages:delete`", "operationId": "deleteMessage", "tags": [ "message" ], "x-required-scopes": [ "messages:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Message.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "4SsY67bC" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/messages/4SsY67bC\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/messages/{id}', {\n params: { path: { id: '4SsY67bC' } },\n});" } ] } }, "/messages/search": { "get": { "summary": "Search Messages", "description": "Full-text ranked search across messages. Ranked by relevance; pages are capped at 200 results. Filterable by 14 fields.\n\n**Required scope:** `messages:read`", "operationId": "searchMessages", "tags": [ "message" ], "x-required-scopes": [ "messages:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "deletedBy", "createdByActor", "updatedByActor", "chat", "task", "document", "file", "annotation", "parentMessage", "sharedDocument", "tagged", "seenBy", "hiddenFor", "files", "replies" ] } }, "style": "form", "explode": false, "example": [ "author", "deletedBy" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "authorId[eq]", "in": "query", "required": false, "description": "Filter where `authorId` equals.", "schema": { "type": "string" }, "example": "EPmKiCaK" }, { "name": "authorId[in]", "in": "query", "required": false, "description": "Filter where `authorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "EPmKiCaK", "EPmKiCaK" ] }, { "name": "chatId[eq]", "in": "query", "required": false, "description": "Filter where `chatId` equals.", "schema": { "type": "string" }, "example": "hTIeouEK" }, { "name": "chatId[in]", "in": "query", "required": false, "description": "Filter where `chatId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "hTIeouEK", "hTIeouEK" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "documentId[eq]", "in": "query", "required": false, "description": "Filter where `documentId` equals.", "schema": { "type": "string" }, "example": "ELe0nkum" }, { "name": "documentId[in]", "in": "query", "required": false, "description": "Filter where `documentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ELe0nkum", "ELe0nkum" ] }, { "name": "fileId[eq]", "in": "query", "required": false, "description": "Filter where `fileId` equals.", "schema": { "type": "string" }, "example": "xvM2toUM" }, { "name": "fileId[in]", "in": "query", "required": false, "description": "Filter where `fileId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "xvM2toUM", "xvM2toUM" ] }, { "name": "annotationId[eq]", "in": "query", "required": false, "description": "Filter where `annotationId` equals.", "schema": { "type": "string" }, "example": "863BiyIc" }, { "name": "annotationId[in]", "in": "query", "required": false, "description": "Filter where `annotationId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "863BiyIc", "863BiyIc" ] }, { "name": "parentMessageId[eq]", "in": "query", "required": false, "description": "Filter where `parentMessageId` equals.", "schema": { "type": "string" }, "example": "gx21BskY" }, { "name": "parentMessageId[in]", "in": "query", "required": false, "description": "Filter where `parentMessageId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "gx21BskY", "gx21BskY" ] }, { "name": "sharedDocumentId[eq]", "in": "query", "required": false, "description": "Filter where `sharedDocumentId` equals.", "schema": { "type": "string" }, "example": "vjciEwQy" }, { "name": "sharedDocumentId[in]", "in": "query", "required": false, "description": "Filter where `sharedDocumentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "vjciEwQy", "vjciEwQy" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "text", "gif", "document", "audio" ] }, "example": "text" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "text", "gif", "document", "audio" ] } }, "example": [ "text", "gif" ] }, { "name": "subtype[eq]", "in": "query", "required": false, "description": "Filter where `subtype` equals.", "schema": { "type": "string", "enum": [ "hello", "joinProject", "joinChat", "createTask", "archiveTask", "unarchiveTask", "addTaskDeadline", "removeTaskDeadline", "completeTask", "moveTask", "moveSubtask", "convertToTask", "untieTask", "tieTask", "assignTask", "unassignTask", "moveProject", "meetingStart", "meetingEnd", "mentionTaskInCommit", "mentionTaskInPR", "addTaskStartDate", "removeTaskStartDate", "sendMessage", "unCompleteTask", "enableRecurringOnTask", "taskAddLabel", "taskRemoveLabel", "taskAddAssignee", "taskRemoveAssignee", "taskAddGoal", "taskRemoveGoal", "taskUpdateDependency", "taskUpdateField", "taskUpdateReminder", "taskUpdateStoryPoints", "timeEntryCreate", "taskOverdue", "taskAddChecklist", "taskRemoveChecklist", "taskUpdateChecklist", "taskAddChecklistItem", "taskRemoveChecklistItem", "taskUpdateChecklistItem", "taskCompleteChecklistItem", "taskUncompleteChecklistItem", "taskAddLabeledAssignee", "taskRemoveLabeledAssignee", "timeEntryEdited", "timeEntryRemoved", "taskAddSubscriber", "taskRemoveSubscriber" ] }, "example": "hello" }, { "name": "subtype[in]", "in": "query", "required": false, "description": "Filter where `subtype` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "hello", "joinProject", "joinChat", "createTask", "archiveTask", "unarchiveTask", "addTaskDeadline", "removeTaskDeadline", "completeTask", "moveTask", "moveSubtask", "convertToTask", "untieTask", "tieTask", "assignTask", "unassignTask", "moveProject", "meetingStart", "meetingEnd", "mentionTaskInCommit", "mentionTaskInPR", "addTaskStartDate", "removeTaskStartDate", "sendMessage", "unCompleteTask", "enableRecurringOnTask", "taskAddLabel", "taskRemoveLabel", "taskAddAssignee", "taskRemoveAssignee", "taskAddGoal", "taskRemoveGoal", "taskUpdateDependency", "taskUpdateField", "taskUpdateReminder", "taskUpdateStoryPoints", "timeEntryCreate", "taskOverdue", "taskAddChecklist", "taskRemoveChecklist", "taskUpdateChecklist", "taskAddChecklistItem", "taskRemoveChecklistItem", "taskUpdateChecklistItem", "taskCompleteChecklistItem", "taskUncompleteChecklistItem", "taskAddLabeledAssignee", "taskRemoveLabeledAssignee", "timeEntryEdited", "timeEntryRemoved", "taskAddSubscriber", "taskRemoveSubscriber" ] } }, "example": [ "hello", "joinProject" ] }, { "name": "subtype[null]", "in": "query", "required": false, "description": "Filter where `subtype` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "subtype[notNull]", "in": "query", "required": false, "description": "Filter where `subtype` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "isEdited[eq]", "in": "query", "required": false, "description": "Filter where `isEdited` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/messageExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "4SsY67bC", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] }, { "id": "yNKAKwWM", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/messages/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/messages/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/messages/{id}/restore": { "post": { "summary": "Restore Message", "description": "Restore a Message that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `messages:delete`", "operationId": "restoreMessage", "tags": [ "message" ], "x-required-scopes": [ "messages:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Message.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "4SsY67bC" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/message" }, "examples": { "default": { "value": { "id": "4SsY67bC", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "2MuAM0jY", "teamId": "cfC83TeS", "text": "Looks good — shipping this today.", "url": "https://example.com/resource", "type": "text", "subtype": "hello", "isEdited": false, "hideLinkPreview": false, "botName": "Example", "botAvatar": "https://cdn.nifty.pm/example.png", "audioDuration": 100, "editHistory": [], "authorId": "EPmKiCaK", "chatId": "hTIeouEK", "taskId": "KfS0ha8P", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "annotationId": "863BiyIc", "parentMessageId": "gx21BskY", "sharedDocumentId": "vjciEwQy", "mentions": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "repliesCount": 3, "repliers": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "messages:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/messages/4SsY67bC/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/messages/{id}/restore', {\n params: { path: { id: '4SsY67bC' } },\n});" } ] } }, "/portfolios": { "get": { "summary": "List Portfolios", "description": "List portfolios. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `portfolios:read`", "operationId": "listPortfolios", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "-name", "-order", "-createdAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "createdByActor", "updatedByActor", "deletedBy", "members" ] } }, "style": "form", "explode": false, "example": [ "owner", "createdByActor" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "isGeneral[eq]", "in": "query", "required": false, "description": "Filter where `isGeneral` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "order[eq]", "in": "query", "required": false, "description": "Filter where `order` equals.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[gt]", "in": "query", "required": false, "description": "Filter where `order` is greater than.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[gte]", "in": "query", "required": false, "description": "Filter where `order` is greater than or equal to.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[lt]", "in": "query", "required": false, "description": "Filter where `order` is less than.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[lte]", "in": "query", "required": false, "description": "Filter where `order` is less than or equal to.", "schema": { "type": "number" }, "example": 2000 }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/portfolioExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "1YEYsy2X", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2000, "ownerId": "QpCuKyI2" }, { "id": "Z1lukoik", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Second example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2001, "ownerId": "QpCuKyI2" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/portfolios\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/portfolios');" } ] }, "post": { "summary": "Create Portfolio", "description": "Create a Portfolio. Server-assigned fields are ignored if sent.\n\n**Required scope:** `portfolios:write`", "operationId": "createPortfolio", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "createdByActor", "updatedByActor", "deletedBy", "members" ] } }, "style": "form", "explode": false, "example": [ "owner", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portfolioCreate" }, "examples": { "default": { "value": { "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "order": 2000, "members": [ "P3hYIKqK" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portfolioExpanded" }, "examples": { "default": { "value": { "id": "1YEYsy2X", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2000, "ownerId": "QpCuKyI2" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/portfolios\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"icon\":\"https://cdn.nifty.pm/example.png\",\"initials\":\"NB\",\"color\":\"#00A99B\",\"order\":2000,\"members\":[\"P3hYIKqK\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/portfolios', {\n body: {\n \"name\": \"Example\",\n \"icon\": \"https://cdn.nifty.pm/example.png\",\n \"initials\": \"NB\",\n \"color\": \"#00A99B\",\n \"order\": 2000,\n \"members\": [\n \"P3hYIKqK\"\n ]\n },\n});" } ] } }, "/portfolios/{id}": { "get": { "summary": "Get Portfolio", "description": "Retrieve a single Portfolio by id.\n\n**Required scope:** `portfolios:read`", "operationId": "getPortfolio", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Portfolio.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "1YEYsy2X" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "createdByActor", "updatedByActor", "deletedBy", "members" ] } }, "style": "form", "explode": false, "example": [ "owner", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portfolioExpanded" }, "examples": { "default": { "value": { "id": "1YEYsy2X", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2000, "ownerId": "QpCuKyI2" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/portfolios/1YEYsy2X\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/portfolios/{id}', {\n params: { path: { id: '1YEYsy2X' } },\n});" } ] }, "patch": { "summary": "Update Portfolio", "description": "Partially update a Portfolio. Only the fields you send are changed.\n\n**Required scope:** `portfolios:write`", "operationId": "updatePortfolio", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Portfolio.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "1YEYsy2X" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "createdByActor", "updatedByActor", "deletedBy", "members" ] } }, "style": "form", "explode": false, "example": [ "owner", "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portfolioUpdate" }, "examples": { "default": { "value": { "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "ownerId": "QpCuKyI2", "order": 2000, "members": [ "P3hYIKqK" ], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portfolioExpanded" }, "examples": { "default": { "value": { "id": "1YEYsy2X", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2000, "ownerId": "QpCuKyI2" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/portfolios/1YEYsy2X\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"icon\":\"https://cdn.nifty.pm/example.png\",\"initials\":\"NB\",\"color\":\"#00A99B\",\"ownerId\":\"QpCuKyI2\",\"order\":2000,\"members\":[\"P3hYIKqK\"],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/portfolios/{id}', {\n params: { path: { id: '1YEYsy2X' } },\n body: {\n \"name\": \"Example\",\n \"icon\": \"https://cdn.nifty.pm/example.png\",\n \"initials\": \"NB\",\n \"color\": \"#00A99B\",\n \"ownerId\": \"QpCuKyI2\",\n \"order\": 2000,\n \"members\": [\n \"P3hYIKqK\"\n ],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Portfolio", "description": "Move this Portfolio to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `portfolios:delete`", "operationId": "deletePortfolio", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Portfolio.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "1YEYsy2X" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/portfolios/1YEYsy2X\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/portfolios/{id}', {\n params: { path: { id: '1YEYsy2X' } },\n});" } ] } }, "/portfolios/search": { "get": { "summary": "Search Portfolios", "description": "Full-text ranked search across portfolios. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.\n\n**Required scope:** `portfolios:read`", "operationId": "searchPortfolios", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "createdByActor", "updatedByActor", "deletedBy", "members" ] } }, "style": "form", "explode": false, "example": [ "owner", "createdByActor" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "isGeneral[eq]", "in": "query", "required": false, "description": "Filter where `isGeneral` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "order[eq]", "in": "query", "required": false, "description": "Filter where `order` equals.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[gt]", "in": "query", "required": false, "description": "Filter where `order` is greater than.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[gte]", "in": "query", "required": false, "description": "Filter where `order` is greater than or equal to.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[lt]", "in": "query", "required": false, "description": "Filter where `order` is less than.", "schema": { "type": "number" }, "example": 2000 }, { "name": "order[lte]", "in": "query", "required": false, "description": "Filter where `order` is less than or equal to.", "schema": { "type": "number" }, "example": 2000 }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/portfolioExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "1YEYsy2X", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2000, "ownerId": "QpCuKyI2" }, { "id": "Z1lukoik", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Second example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2001, "ownerId": "QpCuKyI2" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/portfolios/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/portfolios/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/portfolios/{id}/members": { "post": { "summary": "Add members to a Portfolio", "description": "Link the given ids to this Portfolio as members. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete members set afterwards.\n\n**Required scopes:** `portfolios:write` `portfolios:link`", "operationId": "addPortfolioMembers", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:write", "portfolios:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Portfolio.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "1YEYsy2X" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete members set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:write", "portfolios:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/portfolios/1YEYsy2X/members\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/portfolios/{id}/members', {\n params: { path: { id: '1YEYsy2X' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/portfolios/{id}/members/remove": { "post": { "summary": "Remove members from a Portfolio", "description": "Unlink the given ids from this Portfolio's members. Removing one that is not linked changes nothing. Returns the complete members set afterwards.\n\n**Required scopes:** `portfolios:write` `portfolios:link`", "operationId": "removePortfolioMembers", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:write", "portfolios:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Portfolio.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "1YEYsy2X" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete members set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:write", "portfolios:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/portfolios/1YEYsy2X/members/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/portfolios/{id}/members/remove', {\n params: { path: { id: '1YEYsy2X' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/portfolios/{id}/restore": { "post": { "summary": "Restore Portfolio", "description": "Restore a Portfolio that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `portfolios:delete`", "operationId": "restorePortfolio", "tags": [ "portfolio" ], "x-required-scopes": [ "portfolios:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Portfolio.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "1YEYsy2X" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/portfolio" }, "examples": { "default": { "value": { "id": "1YEYsy2X", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "RzEGIS2T", "name": "Example", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "isGeneral": false, "order": 2000, "ownerId": "QpCuKyI2" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "portfolios:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/portfolios/1YEYsy2X/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/portfolios/{id}/restore', {\n params: { path: { id: '1YEYsy2X' } },\n});" } ] } }, "/presence-statuses": { "get": { "summary": "List Presence Statuses", "description": "List presenceStatuses. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `presence-statuses:read`", "operationId": "listPresenceStatuses", "tags": [ "presenceStatus" ], "x-required-scopes": [ "presence-statuses:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "isDefault[eq]", "in": "query", "required": false, "description": "Filter where `isDefault` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "appearsOnline[eq]", "in": "query", "required": false, "description": "Filter where `appearsOnline` equals.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/presenceStatusExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "WjkiuqmY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false }, { "id": "4u2zIoka", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "presence-statuses:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/presence-statuses\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/presence-statuses');" } ] }, "post": { "summary": "Create Presence Status", "description": "Create a Presence Status. Server-assigned fields are ignored if sent.\n\n**Required scope:** `presence-statuses:write`", "operationId": "createPresenceStatus", "tags": [ "presenceStatus" ], "x-required-scopes": [ "presence-statuses:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenceStatusCreate" }, "examples": { "default": { "value": { "name": "Example", "appearsOnline": false, "emoji": ":rocket:", "muteNotifications": false, "defaultDurationMs": 3600000 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenceStatusExpanded" }, "examples": { "default": { "value": { "id": "WjkiuqmY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "presence-statuses:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/presence-statuses\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"appearsOnline\":false,\"emoji\":\":rocket:\",\"muteNotifications\":false,\"defaultDurationMs\":3600000}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/presence-statuses', {\n body: {\n \"name\": \"Example\",\n \"appearsOnline\": false,\n \"emoji\": \":rocket:\",\n \"muteNotifications\": false,\n \"defaultDurationMs\": 3600000\n },\n});" } ] } }, "/presence-statuses/{id}": { "get": { "summary": "Get Presence Status", "description": "Retrieve a single Presence Status by id.\n\n**Required scope:** `presence-statuses:read`", "operationId": "getPresenceStatus", "tags": [ "presenceStatus" ], "x-required-scopes": [ "presence-statuses:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Presence Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "WjkiuqmY" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenceStatusExpanded" }, "examples": { "default": { "value": { "id": "WjkiuqmY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "presence-statuses:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/presence-statuses/WjkiuqmY\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/presence-statuses/{id}', {\n params: { path: { id: 'WjkiuqmY' } },\n});" } ] }, "patch": { "summary": "Update Presence Status", "description": "Partially update a Presence Status. Only the fields you send are changed.\n\n**Required scope:** `presence-statuses:write`", "operationId": "updatePresenceStatus", "tags": [ "presenceStatus" ], "x-required-scopes": [ "presence-statuses:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Presence Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "WjkiuqmY" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenceStatusUpdate" }, "examples": { "default": { "value": { "name": "Example", "appearsOnline": false, "emoji": ":rocket:", "muteNotifications": false, "defaultDurationMs": 3600000, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/presenceStatusExpanded" }, "examples": { "default": { "value": { "id": "WjkiuqmY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "presence-statuses:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/presence-statuses/WjkiuqmY\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"appearsOnline\":false,\"emoji\":\":rocket:\",\"muteNotifications\":false,\"defaultDurationMs\":3600000,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/presence-statuses/{id}', {\n params: { path: { id: 'WjkiuqmY' } },\n body: {\n \"name\": \"Example\",\n \"appearsOnline\": false,\n \"emoji\": \":rocket:\",\n \"muteNotifications\": false,\n \"defaultDurationMs\": 3600000,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Presence Status", "description": "Permanently delete this Presence Status. This cannot be undone.\n\n**Required scope:** `presence-statuses:delete`", "operationId": "deletePresenceStatus", "tags": [ "presenceStatus" ], "x-required-scopes": [ "presence-statuses:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Presence Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "WjkiuqmY" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "presence-statuses:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/presence-statuses/WjkiuqmY\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/presence-statuses/{id}', {\n params: { path: { id: 'WjkiuqmY' } },\n});" } ] } }, "/presence-statuses/search": { "get": { "summary": "Search Presence Statuses", "description": "Full-text ranked search across presenceStatuses. Ranked by relevance; pages are capped at 200 results. Filterable by 3 fields.\n\n**Required scope:** `presence-statuses:read`", "operationId": "searchPresenceStatuses", "tags": [ "presenceStatus" ], "x-required-scopes": [ "presence-statuses:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "isDefault[eq]", "in": "query", "required": false, "description": "Filter where `isDefault` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "appearsOnline[eq]", "in": "query", "required": false, "description": "Filter where `appearsOnline` equals.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/presenceStatusExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "WjkiuqmY", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false }, { "id": "4u2zIoka", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "emoji": ":rocket:", "appearsOnline": false, "muteNotifications": false, "defaultDurationMs": 3600000, "isDefault": false } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "presence-statuses:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/presence-statuses/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/presence-statuses/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/projects": { "get": { "summary": "List Projects", "description": "List projects. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `projects:read`", "operationId": "listProjects", "tags": [ "project" ], "x-required-scopes": [ "projects:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "updatedAt", "order", "-name", "-createdAt", "-updatedAt", "-order" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "deletedBy", "members", "portfolio", "discussionChat", "customFields" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "accessType[eq]", "in": "query", "required": false, "description": "Filter where `accessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited" ] }, "example": "public" }, { "name": "accessType[in]", "in": "query", "required": false, "description": "Filter where `accessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited" ] } }, "example": [ "public", "limited" ] }, { "name": "portfolioId[eq]", "in": "query", "required": false, "description": "Filter where `portfolioId` equals.", "schema": { "type": "string" }, "example": "1YEYsy2X" }, { "name": "portfolioId[in]", "in": "query", "required": false, "description": "Filter where `portfolioId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "1YEYsy2X", "1YEYsy2X" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/projectExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" }, { "id": "yZCY8Lac", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "Second pRJ", "name": "Second example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/projects\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/projects');" } ] }, "post": { "summary": "Create Project", "description": "Create a Project. Server-assigned fields are ignored if sent.\n\n**Required scope:** `projects:write`", "operationId": "createProject", "tags": [ "project" ], "x-required-scopes": [ "projects:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "deletedBy", "members", "portfolio", "discussionChat", "customFields" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "members": [ "P3hYIKqK" ], "projectFolderId": "0sSAIGwG", "customFields": [] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectExpanded" }, "examples": { "default": { "value": { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/projects\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"icon\":\"https://cdn.nifty.pm/example.png\",\"initials\":\"NB\",\"color\":\"#00A99B\",\"secondaryColor\":\"#0E7C74\",\"portfolioId\":\"1YEYsy2X\",\"accessType\":\"public\",\"modules\":[\"home\"],\"defaultTasksView\":\"table\",\"hiddenListColumns\":[\"estimate\",\"labels\"],\"listColumnsOrder\":[\"name\",\"assignee\",\"dueDate\"],\"customFieldsOrder\":[\"cf_6GWCcskG\",\"cf_qHsUISQS\"],\"taskCustomFieldsOrder\":[\"cf_6GWCcskG\",\"cf_qHsUISQS\"],\"listCustomFieldsOrder\":[\"cf_6GWCcskG\",\"cf_qHsUISQS\"],\"autoMilestones\":false,\"hideUsersFromGuests\":false,\"subtaskStatusEnabled\":false,\"queryAllFiles\":false,\"members\":[\"P3hYIKqK\"],\"projectFolderId\":\"0sSAIGwG\",\"customFields\":[]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/projects', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"icon\": \"https://cdn.nifty.pm/example.png\",\n \"initials\": \"NB\",\n \"color\": \"#00A99B\",\n \"secondaryColor\": \"#0E7C74\",\n \"portfolioId\": \"1YEYsy2X\",\n \"accessType\": \"public\",\n \"modules\": [\n \"home\"\n ],\n \"defaultTasksView\": \"table\",\n \"hiddenListColumns\": [\n \"estimate\",\n \"labels\"\n ],\n \"listColumnsOrder\": [\n \"name\",\n \"assignee\",\n \"dueDate\"\n ],\n \"customFieldsOrder\": [\n \"cf_6GWCcskG\",\n \"cf_qHsUISQS\"\n ],\n \"taskCustomFieldsOrder\": [\n \"cf_6GWCcskG\",\n \"cf_qHsUISQS\"\n ],\n \"listCustomFieldsOrder\": [\n \"cf_6GWCcskG\",\n \"cf_qHsUISQS\"\n ],\n \"autoMilestones\": false,\n \"hideUsersFromGuests\": false,\n \"subtaskStatusEnabled\": false,\n \"queryAllFiles\": false,\n \"members\": [\n \"P3hYIKqK\"\n ],\n \"projectFolderId\": \"0sSAIGwG\",\n \"customFields\": []\n },\n});" } ] } }, "/projects/{id}": { "get": { "summary": "Get Project", "description": "Retrieve a single Project by id.\n\n**Required scope:** `projects:read`", "operationId": "getProject", "tags": [ "project" ], "x-required-scopes": [ "projects:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "deletedBy", "members", "portfolio", "discussionChat", "customFields" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectExpanded" }, "examples": { "default": { "value": { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/projects/{id}', {\n params: { path: { id: 'iV6vIU8N' } },\n});" } ] }, "patch": { "summary": "Update Project", "description": "Partially update a Project. Only the fields you send are changed.\n\n**Required scope:** `projects:write`", "operationId": "updateProject", "tags": [ "project" ], "x-required-scopes": [ "projects:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "deletedBy", "members", "portfolio", "discussionChat", "customFields" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "archived": false, "accessType": "public", "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "members": [ "P3hYIKqK" ], "projectFolderId": "0sSAIGwG", "customFields": [], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectExpanded" }, "examples": { "default": { "value": { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"icon\":\"https://cdn.nifty.pm/example.png\",\"initials\":\"NB\",\"color\":\"#00A99B\",\"secondaryColor\":\"#0E7C74\",\"archived\":false,\"accessType\":\"public\",\"defaultTasksView\":\"table\",\"hiddenListColumns\":[\"estimate\",\"labels\"],\"listColumnsOrder\":[\"name\",\"assignee\",\"dueDate\"],\"customFieldsOrder\":[\"cf_6GWCcskG\",\"cf_qHsUISQS\"],\"taskCustomFieldsOrder\":[\"cf_6GWCcskG\",\"cf_qHsUISQS\"],\"listCustomFieldsOrder\":[\"cf_6GWCcskG\",\"cf_qHsUISQS\"],\"autoMilestones\":false,\"hideUsersFromGuests\":false,\"subtaskStatusEnabled\":false,\"queryAllFiles\":false,\"members\":[\"P3hYIKqK\"],\"projectFolderId\":\"0sSAIGwG\",\"customFields\":[],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/projects/{id}', {\n params: { path: { id: 'iV6vIU8N' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"icon\": \"https://cdn.nifty.pm/example.png\",\n \"initials\": \"NB\",\n \"color\": \"#00A99B\",\n \"secondaryColor\": \"#0E7C74\",\n \"archived\": false,\n \"accessType\": \"public\",\n \"defaultTasksView\": \"table\",\n \"hiddenListColumns\": [\n \"estimate\",\n \"labels\"\n ],\n \"listColumnsOrder\": [\n \"name\",\n \"assignee\",\n \"dueDate\"\n ],\n \"customFieldsOrder\": [\n \"cf_6GWCcskG\",\n \"cf_qHsUISQS\"\n ],\n \"taskCustomFieldsOrder\": [\n \"cf_6GWCcskG\",\n \"cf_qHsUISQS\"\n ],\n \"listCustomFieldsOrder\": [\n \"cf_6GWCcskG\",\n \"cf_qHsUISQS\"\n ],\n \"autoMilestones\": false,\n \"hideUsersFromGuests\": false,\n \"subtaskStatusEnabled\": false,\n \"queryAllFiles\": false,\n \"members\": [\n \"P3hYIKqK\"\n ],\n \"projectFolderId\": \"0sSAIGwG\",\n \"customFields\": [],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Project", "description": "Move this Project to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `projects:delete`", "operationId": "deleteProject", "tags": [ "project" ], "x-required-scopes": [ "projects:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/projects/{id}', {\n params: { path: { id: 'iV6vIU8N' } },\n});" } ] } }, "/projects/search": { "get": { "summary": "Search Projects", "description": "Full-text ranked search across projects. Ranked by relevance; pages are capped at 200 results. Filterable by 6 fields.\n\n**Required scope:** `projects:read`", "operationId": "searchProjects", "tags": [ "project" ], "x-required-scopes": [ "projects:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor", "deletedBy", "members", "portfolio", "discussionChat", "customFields" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "accessType[eq]", "in": "query", "required": false, "description": "Filter where `accessType` equals.", "schema": { "type": "string", "enum": [ "public", "limited" ] }, "example": "public" }, { "name": "accessType[in]", "in": "query", "required": false, "description": "Filter where `accessType` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "public", "limited" ] } }, "example": [ "public", "limited" ] }, { "name": "portfolioId[eq]", "in": "query", "required": false, "description": "Filter where `portfolioId` equals.", "schema": { "type": "string" }, "example": "1YEYsy2X" }, { "name": "portfolioId[in]", "in": "query", "required": false, "description": "Filter where `portfolioId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "1YEYsy2X", "1YEYsy2X" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/projectExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" }, { "id": "yZCY8Lac", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "Second pRJ", "name": "Second example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/projects/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/projects/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/projects/{id}/transfer": { "post": { "summary": "Transfer (Project)", "description": "Transfer project ownership to another member.\n\n**Required scope:** `projects:write`", "operationId": "transferProject", "tags": [ "project" ], "x-required-scopes": [ "projects:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "additionalProperties": false }, "examples": { "default": { "value": { "id": "XXKmAKg6", "message": "Example message" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "minLength": 1 } }, "required": [ "memberId" ], "additionalProperties": false }, "examples": { "default": { "value": { "memberId": "P3hYIKqK" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N/transfer\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"memberId\":\"P3hYIKqK\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/projects/{id}/transfer', {\n params: { path: { id: 'iV6vIU8N' } },\n body: {\n \"memberId\": \"P3hYIKqK\"\n },\n});" } ] } }, "/projects/{id}/members": { "post": { "summary": "Add members to a Project", "description": "Add an existing team member to this project.\n\n**Required scope:** `projects:write`", "operationId": "addProjectMembers", "tags": [ "project" ], "x-required-scopes": [ "projects:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ], "additionalProperties": false }, "examples": { "default": { "value": { "id": "XXKmAKg6", "message": "Example message" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "minLength": 1 } }, "required": [ "memberId" ], "additionalProperties": false }, "examples": { "default": { "value": { "memberId": "P3hYIKqK" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N/members\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"memberId\":\"P3hYIKqK\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/projects/{id}/members', {\n params: { path: { id: 'iV6vIU8N' } },\n body: {\n \"memberId\": \"P3hYIKqK\"\n },\n});" } ] } }, "/projects/{id}/members/remove": { "post": { "summary": "Remove members from a Project", "description": "Remove a member from this project.\n\n**Required scope:** `projects:delete`", "operationId": "removeProjectMembers", "tags": [ "project" ], "x-required-scopes": [ "projects:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false }, "examples": { "default": { "value": { "message": "Example message" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:delete" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "minLength": 1 } }, "required": [ "memberId" ], "additionalProperties": false }, "examples": { "default": { "value": { "memberId": "P3hYIKqK" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N/members/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"memberId\":\"P3hYIKqK\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/projects/{id}/members/remove', {\n params: { path: { id: 'iV6vIU8N' } },\n body: {\n \"memberId\": \"P3hYIKqK\"\n },\n});" } ] } }, "/projects/{id}/restore": { "post": { "summary": "Restore Project", "description": "Restore a Project that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `projects:delete`", "operationId": "restoreProject", "tags": [ "project" ], "x-required-scopes": [ "projects:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "iV6vIU8N" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/project" }, "examples": { "default": { "value": { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "projects:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/projects/iV6vIU8N/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/projects/{id}/restore', {\n params: { path: { id: 'iV6vIU8N' } },\n});" } ] } }, "/project-activities": { "get": { "summary": "List Project activities", "description": "List projectActivities. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 8 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `project-activities:read`", "operationId": "listProjectActivities", "tags": [ "projectActivity" ], "x-required-scopes": [ "project-activities:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list projectActivities across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "createdAt", "-createdAt" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "task", "list", "document", "file", "triggeredBy" ] } }, "style": "form", "explode": false, "example": [ "project", "task" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "projectCreated", "usersJoined", "usersLeft", "listCreated", "listMilestoneCreated", "listUnlocked", "taskCompleted", "fileUploaded", "docCreated" ] }, "example": "taskCompleted" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "projectCreated", "usersJoined", "usersLeft", "listCreated", "listMilestoneCreated", "listUnlocked", "taskCompleted", "fileUploaded", "docCreated" ] } }, "example": [ "taskCompleted", "usersJoined" ] }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "listId[eq]", "in": "query", "required": false, "description": "Filter where `listId` equals.", "schema": { "type": "string" }, "example": "lN6ZQycO" }, { "name": "listId[in]", "in": "query", "required": false, "description": "Filter where `listId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "lN6ZQycO", "lN6ZQycO" ] }, { "name": "documentId[eq]", "in": "query", "required": false, "description": "Filter where `documentId` equals.", "schema": { "type": "string" }, "example": "ELe0nkum" }, { "name": "documentId[in]", "in": "query", "required": false, "description": "Filter where `documentId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ELe0nkum", "ELe0nkum" ] }, { "name": "fileId[eq]", "in": "query", "required": false, "description": "Filter where `fileId` equals.", "schema": { "type": "string" }, "example": "xvM2toUM" }, { "name": "fileId[in]", "in": "query", "required": false, "description": "Filter where `fileId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "xvM2toUM", "xvM2toUM" ] }, { "name": "triggeredById[eq]", "in": "query", "required": false, "description": "Filter where `triggeredById` equals.", "schema": { "type": "string" }, "example": "lvc47DE8" }, { "name": "triggeredById[in]", "in": "query", "required": false, "description": "Filter where `triggeredById` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "lvc47DE8", "lvc47DE8" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/projectActivityExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "Nl0Hmwsa", "createdAt": "2026-05-31T12:00:00.000Z", "projectId": "iV6vIU8N", "type": "taskCompleted", "taskId": "KfS0ha8P", "listId": "lN6ZQycO", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "memberId": "P3hYIKqK", "triggeredById": "lvc47DE8" }, { "id": "FnUQsma0", "createdAt": "2026-05-31T12:00:00.000Z", "projectId": "iV6vIU8N", "type": "taskCompleted", "taskId": "KfS0ha8P", "listId": "lN6ZQycO", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "memberId": "P3hYIKqK", "triggeredById": "lvc47DE8" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-activities:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/project-activities\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/project-activities');" } ] } }, "/project-activities/{id}": { "get": { "summary": "Get Project activity", "description": "Retrieve a single Project activity by id.\n\n**Required scope:** `project-activities:read`", "operationId": "getProjectActivity", "tags": [ "projectActivity" ], "x-required-scopes": [ "project-activities:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project activity.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Nl0Hmwsa" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "task", "list", "document", "file", "triggeredBy" ] } }, "style": "form", "explode": false, "example": [ "project", "task" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectActivityExpanded" }, "examples": { "default": { "value": { "id": "Nl0Hmwsa", "createdAt": "2026-05-31T12:00:00.000Z", "projectId": "iV6vIU8N", "type": "taskCompleted", "taskId": "KfS0ha8P", "listId": "lN6ZQycO", "documentId": "ELe0nkum", "fileId": "xvM2toUM", "memberId": "P3hYIKqK", "triggeredById": "lvc47DE8" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-activities:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/project-activities/Nl0Hmwsa\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/project-activities/{id}', {\n params: { path: { id: 'Nl0Hmwsa' } },\n});" } ] } }, "/project-dashboards": { "get": { "summary": "List Project Dashboards", "description": "List projectDashboards. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `project-dashboards:read`", "operationId": "listProjectDashboards", "tags": [ "projectDashboard" ], "x-required-scopes": [ "project-dashboards:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list projectDashboards across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "project", "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "isShared[eq]", "in": "query", "required": false, "description": "Filter where `isShared` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "isDefault[eq]", "in": "query", "required": false, "description": "Filter where `isDefault` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "createdById[eq]", "in": "query", "required": false, "description": "Filter where `createdById` equals.", "schema": { "type": "string" }, "example": "JvMMIoOQ" }, { "name": "createdById[in]", "in": "query", "required": false, "description": "Filter where `createdById` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "JvMMIoOQ", "JvMMIoOQ" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/projectDashboardExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "udOQuo4n", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "projectId": "iV6vIU8N", "isShared": false, "isDefault": false, "widgets": [] }, { "id": "k5LAc2b8", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "projectId": "iV6vIU8N", "isShared": false, "isDefault": false, "widgets": [] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-dashboards:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/project-dashboards\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/project-dashboards');" } ] }, "post": { "summary": "Create Project Dashboard", "description": "Create a Project Dashboard. Server-assigned fields are ignored if sent.\n\n**Required scope:** `project-dashboards:write`", "operationId": "createProjectDashboard", "tags": [ "projectDashboard" ], "x-required-scopes": [ "project-dashboards:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "project", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectDashboardCreate" }, "examples": { "default": { "value": { "name": "Example", "projectId": "iV6vIU8N", "isShared": false, "isDefault": false, "widgets": [] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectDashboardExpanded" }, "examples": { "default": { "value": { "id": "udOQuo4n", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "projectId": "iV6vIU8N", "isShared": false, "isDefault": false, "widgets": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-dashboards:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/project-dashboards\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"projectId\":\"iV6vIU8N\",\"isShared\":false,\"isDefault\":false,\"widgets\":[]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/project-dashboards', {\n body: {\n \"name\": \"Example\",\n \"projectId\": \"iV6vIU8N\",\n \"isShared\": false,\n \"isDefault\": false,\n \"widgets\": []\n },\n});" } ] } }, "/project-dashboards/{id}": { "get": { "summary": "Get Project Dashboard", "description": "Retrieve a single Project Dashboard by id.\n\n**Required scope:** `project-dashboards:read`", "operationId": "getProjectDashboard", "tags": [ "projectDashboard" ], "x-required-scopes": [ "project-dashboards:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project Dashboard.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "udOQuo4n" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "project", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectDashboardExpanded" }, "examples": { "default": { "value": { "id": "udOQuo4n", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "projectId": "iV6vIU8N", "isShared": false, "isDefault": false, "widgets": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-dashboards:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/project-dashboards/udOQuo4n\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/project-dashboards/{id}', {\n params: { path: { id: 'udOQuo4n' } },\n});" } ] }, "patch": { "summary": "Update Project Dashboard", "description": "Partially update a Project Dashboard. Only the fields you send are changed.\n\n**Required scope:** `project-dashboards:write`", "operationId": "updateProjectDashboard", "tags": [ "projectDashboard" ], "x-required-scopes": [ "project-dashboards:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project Dashboard.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "udOQuo4n" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "project", "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectDashboardUpdate" }, "examples": { "default": { "value": { "name": "Example", "isShared": false, "isDefault": false, "widgets": [], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectDashboardExpanded" }, "examples": { "default": { "value": { "id": "udOQuo4n", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "projectId": "iV6vIU8N", "isShared": false, "isDefault": false, "widgets": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-dashboards:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/project-dashboards/udOQuo4n\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"isShared\":false,\"isDefault\":false,\"widgets\":[],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/project-dashboards/{id}', {\n params: { path: { id: 'udOQuo4n' } },\n body: {\n \"name\": \"Example\",\n \"isShared\": false,\n \"isDefault\": false,\n \"widgets\": [],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Project Dashboard", "description": "Permanently delete this Project Dashboard. This cannot be undone. The dashboard's widgets are deleted with it.\n\n**Required scope:** `project-dashboards:delete`", "operationId": "deleteProjectDashboard", "tags": [ "projectDashboard" ], "x-required-scopes": [ "project-dashboards:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project Dashboard.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "udOQuo4n" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-dashboards:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/project-dashboards/udOQuo4n\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/project-dashboards/{id}', {\n params: { path: { id: 'udOQuo4n' } },\n});" } ] } }, "/project-folders": { "get": { "summary": "List Project Folders", "description": "List projectFolders. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `project-folders:read`", "operationId": "listProjectFolders", "tags": [ "projectFolder" ], "x-required-scopes": [ "project-folders:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "-name", "-order", "-createdAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "portfolio", "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "portfolio", "projects" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "portfolioId[eq]", "in": "query", "required": false, "description": "Filter where `portfolioId` equals.", "schema": { "type": "string" }, "example": "1YEYsy2X" }, { "name": "portfolioId[in]", "in": "query", "required": false, "description": "Filter where `portfolioId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "1YEYsy2X", "1YEYsy2X" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/projectFolderExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "0sSAIGwG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 200, "portfolioId": "1YEYsy2X" }, { "id": "Y71PgwGs", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "order": 201, "portfolioId": "1YEYsy2X" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-folders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/project-folders\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/project-folders');" } ] }, "post": { "summary": "Create Project Folder", "description": "Create a Project Folder. Server-assigned fields are ignored if sent.\n\n**Required scope:** `project-folders:write`", "operationId": "createProjectFolder", "tags": [ "projectFolder" ], "x-required-scopes": [ "project-folders:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "portfolio", "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "portfolio", "projects" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectFolderCreate" }, "examples": { "default": { "value": { "name": "Example", "order": 200, "portfolioId": "1YEYsy2X" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectFolderExpanded" }, "examples": { "default": { "value": { "id": "0sSAIGwG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 200, "portfolioId": "1YEYsy2X" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-folders:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/project-folders\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":200,\"portfolioId\":\"1YEYsy2X\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/project-folders', {\n body: {\n \"name\": \"Example\",\n \"order\": 200,\n \"portfolioId\": \"1YEYsy2X\"\n },\n});" } ] } }, "/project-folders/{id}": { "get": { "summary": "Get Project Folder", "description": "Retrieve a single Project Folder by id.\n\n**Required scope:** `project-folders:read`", "operationId": "getProjectFolder", "tags": [ "projectFolder" ], "x-required-scopes": [ "project-folders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project Folder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "0sSAIGwG" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "portfolio", "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "portfolio", "projects" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectFolderExpanded" }, "examples": { "default": { "value": { "id": "0sSAIGwG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 200, "portfolioId": "1YEYsy2X" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-folders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/project-folders/0sSAIGwG\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/project-folders/{id}', {\n params: { path: { id: '0sSAIGwG' } },\n});" } ] }, "patch": { "summary": "Update Project Folder", "description": "Partially update a Project Folder. Only the fields you send are changed.\n\n**Required scope:** `project-folders:write`", "operationId": "updateProjectFolder", "tags": [ "projectFolder" ], "x-required-scopes": [ "project-folders:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project Folder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "0sSAIGwG" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "portfolio", "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "portfolio", "projects" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectFolderUpdate" }, "examples": { "default": { "value": { "name": "Example", "order": 200, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/projectFolderExpanded" }, "examples": { "default": { "value": { "id": "0sSAIGwG", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "order": 200, "portfolioId": "1YEYsy2X" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-folders:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/project-folders/0sSAIGwG\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"order\":200,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/project-folders/{id}', {\n params: { path: { id: '0sSAIGwG' } },\n body: {\n \"name\": \"Example\",\n \"order\": 200,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Project Folder", "description": "Permanently delete this Project Folder. This cannot be undone. The projects filed in the folder are NOT deleted — they become unfiled (`projectFolderId: null`).\n\n**Required scope:** `project-folders:delete`", "operationId": "deleteProjectFolder", "tags": [ "projectFolder" ], "x-required-scopes": [ "project-folders:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Project Folder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "0sSAIGwG" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "project-folders:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/project-folders/0sSAIGwG\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/project-folders/{id}', {\n params: { path: { id: '0sSAIGwG' } },\n});" } ] } }, "/recurring-rules": { "get": { "summary": "List Recurring Rules", "description": "List recurringRules. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `recurring-rules:read`", "operationId": "listRecurringRules", "tags": [ "recurringRule" ], "x-required-scopes": [ "recurring-rules:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list recurringRules across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "nextRecurrenceAt", "createdAt", "-nextRecurrenceAt", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "sourceTask", "targetStatus", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "sourceTask", "targetStatus" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "date", "status", "completion", "checkIn" ] }, "example": "date" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "date", "status", "completion", "checkIn" ] } }, "example": [ "date", "status" ] }, { "name": "sourceTaskId[eq]", "in": "query", "required": false, "description": "Filter where `sourceTaskId` equals.", "schema": { "type": "string" }, "example": "5MM8V0rW" }, { "name": "sourceTaskId[in]", "in": "query", "required": false, "description": "Filter where `sourceTaskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "5MM8V0rW", "5MM8V0rW" ] }, { "name": "nextRecurrenceAt[gt]", "in": "query", "required": false, "description": "Filter where `nextRecurrenceAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T16:00:00.000Z" }, { "name": "nextRecurrenceAt[gte]", "in": "query", "required": false, "description": "Filter where `nextRecurrenceAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T16:00:00.000Z" }, { "name": "nextRecurrenceAt[lt]", "in": "query", "required": false, "description": "Filter where `nextRecurrenceAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T16:00:00.000Z" }, { "name": "nextRecurrenceAt[lte]", "in": "query", "required": false, "description": "Filter where `nextRecurrenceAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T16:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/recurringRuleExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "cn2v0xiQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "date", "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "triggerStatusId": "7uM05NSk", "onComplete": false, "sourceTaskId": "5MM8V0rW", "nextRecurrenceAt": "2026-06-01T16:00:00.000Z", "targetStatusId": "00taIogS", "tzIana": "America/New_York", "tzOffset": 100 }, { "id": "6SgEeSmo", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "date", "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "triggerStatusId": "7uM05NSk", "onComplete": false, "sourceTaskId": "5MM8V0rW", "nextRecurrenceAt": "2026-06-01T16:00:00.000Z", "targetStatusId": "00taIogS", "tzIana": "America/New_York", "tzOffset": 100 } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "recurring-rules:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/recurring-rules\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/recurring-rules');" } ] }, "post": { "summary": "Create Recurring Rule", "description": "Create a Recurring Rule. Server-assigned fields are ignored if sent.\n\n**Required scope:** `recurring-rules:write`", "operationId": "createRecurringRule", "tags": [ "recurringRule" ], "x-required-scopes": [ "recurring-rules:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "sourceTask", "targetStatus", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "sourceTask", "targetStatus" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recurringRuleCreate" }, "examples": { "default": { "value": { "type": "date", "sourceTaskId": "5MM8V0rW", "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [ "description" ], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "triggerStatusId": "7uM05NSk" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recurringRuleExpanded" }, "examples": { "default": { "value": { "id": "cn2v0xiQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "date", "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "triggerStatusId": "7uM05NSk", "onComplete": false, "sourceTaskId": "5MM8V0rW", "nextRecurrenceAt": "2026-06-01T16:00:00.000Z", "targetStatusId": "00taIogS", "tzIana": "America/New_York", "tzOffset": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "recurring-rules:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/recurring-rules\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"type\":\"date\",\"sourceTaskId\":\"5MM8V0rW\",\"cron\":\"0 9 * * 1\",\"schedule\":{},\"cloneFields\":[\"description\"],\"dateOffsets\":[],\"end\":\"2026-06-14T12:00:00.000Z\",\"weekParity\":\"off\",\"recurOnDateOnly\":false,\"triggerStatusId\":\"7uM05NSk\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/recurring-rules', {\n body: {\n \"type\": \"date\",\n \"sourceTaskId\": \"5MM8V0rW\",\n \"cron\": \"0 9 * * 1\",\n \"schedule\": {},\n \"cloneFields\": [\n \"description\"\n ],\n \"dateOffsets\": [],\n \"end\": \"2026-06-14T12:00:00.000Z\",\n \"weekParity\": \"off\",\n \"recurOnDateOnly\": false,\n \"triggerStatusId\": \"7uM05NSk\"\n },\n});" } ] } }, "/recurring-rules/{id}": { "get": { "summary": "Get Recurring Rule", "description": "Retrieve a single Recurring Rule by id.\n\n**Required scope:** `recurring-rules:read`", "operationId": "getRecurringRule", "tags": [ "recurringRule" ], "x-required-scopes": [ "recurring-rules:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Recurring Rule.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "cn2v0xiQ" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "sourceTask", "targetStatus", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "sourceTask", "targetStatus" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recurringRuleExpanded" }, "examples": { "default": { "value": { "id": "cn2v0xiQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "date", "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "triggerStatusId": "7uM05NSk", "onComplete": false, "sourceTaskId": "5MM8V0rW", "nextRecurrenceAt": "2026-06-01T16:00:00.000Z", "targetStatusId": "00taIogS", "tzIana": "America/New_York", "tzOffset": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "recurring-rules:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/recurring-rules/cn2v0xiQ\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/recurring-rules/{id}', {\n params: { path: { id: 'cn2v0xiQ' } },\n});" } ] }, "patch": { "summary": "Update Recurring Rule", "description": "Partially update a Recurring Rule. Only the fields you send are changed.\n\n**Required scope:** `recurring-rules:write`", "operationId": "updateRecurringRule", "tags": [ "recurringRule" ], "x-required-scopes": [ "recurring-rules:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Recurring Rule.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "cn2v0xiQ" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "sourceTask", "targetStatus", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "sourceTask", "targetStatus" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recurringRuleUpdate" }, "examples": { "default": { "value": { "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [ "description" ], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/recurringRuleExpanded" }, "examples": { "default": { "value": { "id": "cn2v0xiQ", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "type": "date", "cron": "0 9 * * 1", "schedule": {}, "cloneFields": [], "dateOffsets": [], "end": "2026-06-14T12:00:00.000Z", "weekParity": "off", "recurOnDateOnly": false, "triggerStatusId": "7uM05NSk", "onComplete": false, "sourceTaskId": "5MM8V0rW", "nextRecurrenceAt": "2026-06-01T16:00:00.000Z", "targetStatusId": "00taIogS", "tzIana": "America/New_York", "tzOffset": 100 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "recurring-rules:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/recurring-rules/cn2v0xiQ\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"cron\":\"0 9 * * 1\",\"schedule\":{},\"cloneFields\":[\"description\"],\"dateOffsets\":[],\"end\":\"2026-06-14T12:00:00.000Z\",\"weekParity\":\"off\",\"recurOnDateOnly\":false,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/recurring-rules/{id}', {\n params: { path: { id: 'cn2v0xiQ' } },\n body: {\n \"cron\": \"0 9 * * 1\",\n \"schedule\": {},\n \"cloneFields\": [\n \"description\"\n ],\n \"dateOffsets\": [],\n \"end\": \"2026-06-14T12:00:00.000Z\",\n \"weekParity\": \"off\",\n \"recurOnDateOnly\": false,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Recurring Rule", "description": "Permanently delete this Recurring Rule. This cannot be undone.\n\n**Required scope:** `recurring-rules:delete`", "operationId": "deleteRecurringRule", "tags": [ "recurringRule" ], "x-required-scopes": [ "recurring-rules:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Recurring Rule.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "cn2v0xiQ" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "recurring-rules:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/recurring-rules/cn2v0xiQ\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/recurring-rules/{id}', {\n params: { path: { id: 'cn2v0xiQ' } },\n});" } ] } }, "/reminders": { "get": { "summary": "List Reminders", "description": "List reminders. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `date` unless you pass `sort`.\n\n**Required scope:** `reminders:read`", "operationId": "listReminders", "tags": [ "reminder" ], "x-required-scopes": [ "reminders:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list reminders across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `date`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "date", "createdAt", "-date", "-createdAt" ] }, "example": "date" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "type[eq]", "in": "query", "required": false, "description": "Filter where `type` equals.", "schema": { "type": "string", "enum": [ "overdue", "custom" ] }, "example": "custom" }, { "name": "type[in]", "in": "query", "required": false, "description": "Filter where `type` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "overdue", "custom" ] } }, "example": [ "custom", "custom" ] }, { "name": "date[eq]", "in": "query", "required": false, "description": "Filter where `date` equals.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T09:00:00.000Z" }, { "name": "date[gt]", "in": "query", "required": false, "description": "Filter where `date` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T09:00:00.000Z" }, { "name": "date[gte]", "in": "query", "required": false, "description": "Filter where `date` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T09:00:00.000Z" }, { "name": "date[lt]", "in": "query", "required": false, "description": "Filter where `date` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T09:00:00.000Z" }, { "name": "date[lte]", "in": "query", "required": false, "description": "Filter where `date` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-09-01T09:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/reminderExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "PHIAeeke", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "date": "2026-09-01T09:00:00.000Z", "type": "custom", "taskId": "KfS0ha8P", "createdById": "cRGcC2vM" }, { "id": "hRM6LE0z", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "date": "2026-09-01T09:00:00.000Z", "type": "custom", "taskId": "KfS0ha8P", "createdById": "cRGcC2vM" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "reminders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/reminders\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/reminders');" } ] }, "post": { "summary": "Create Reminder", "description": "Create a Reminder. Server-assigned fields are ignored if sent.\n\n**Required scope:** `reminders:write`", "operationId": "createReminder", "tags": [ "reminder" ], "x-required-scopes": [ "reminders:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reminderCreate" }, "examples": { "default": { "value": { "date": "2026-09-01T09:00:00.000Z", "type": "custom", "taskId": "KfS0ha8P" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reminderExpanded" }, "examples": { "default": { "value": { "id": "PHIAeeke", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "date": "2026-09-01T09:00:00.000Z", "type": "custom", "taskId": "KfS0ha8P", "createdById": "cRGcC2vM" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "reminders:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/reminders\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"date\":\"2026-09-01T09:00:00.000Z\",\"type\":\"custom\",\"taskId\":\"KfS0ha8P\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/reminders', {\n body: {\n \"date\": \"2026-09-01T09:00:00.000Z\",\n \"type\": \"custom\",\n \"taskId\": \"KfS0ha8P\"\n },\n});" } ] } }, "/reminders/{id}": { "get": { "summary": "Get Reminder", "description": "Retrieve a single Reminder by id.\n\n**Required scope:** `reminders:read`", "operationId": "getReminder", "tags": [ "reminder" ], "x-required-scopes": [ "reminders:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Reminder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "PHIAeeke" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reminderExpanded" }, "examples": { "default": { "value": { "id": "PHIAeeke", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "date": "2026-09-01T09:00:00.000Z", "type": "custom", "taskId": "KfS0ha8P", "createdById": "cRGcC2vM" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "reminders:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/reminders/PHIAeeke\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/reminders/{id}', {\n params: { path: { id: 'PHIAeeke' } },\n});" } ] }, "patch": { "summary": "Update Reminder", "description": "Partially update a Reminder. Only the fields you send are changed.\n\n**Required scope:** `reminders:write`", "operationId": "updateReminder", "tags": [ "reminder" ], "x-required-scopes": [ "reminders:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Reminder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "PHIAeeke" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reminderUpdate" }, "examples": { "default": { "value": { "date": "2026-09-01T09:00:00.000Z", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reminderExpanded" }, "examples": { "default": { "value": { "id": "PHIAeeke", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "date": "2026-09-01T09:00:00.000Z", "type": "custom", "taskId": "KfS0ha8P", "createdById": "cRGcC2vM" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "reminders:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/reminders/PHIAeeke\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"date\":\"2026-09-01T09:00:00.000Z\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/reminders/{id}', {\n params: { path: { id: 'PHIAeeke' } },\n body: {\n \"date\": \"2026-09-01T09:00:00.000Z\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Reminder", "description": "Permanently delete this Reminder. This cannot be undone.\n\n**Required scope:** `reminders:delete`", "operationId": "deleteReminder", "tags": [ "reminder" ], "x-required-scopes": [ "reminders:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Reminder.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "PHIAeeke" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "reminders:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/reminders/PHIAeeke\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/reminders/{id}', {\n params: { path: { id: 'PHIAeeke' } },\n});" } ] } }, "/report-charts": { "get": { "summary": "List Report Charts", "description": "List reportCharts. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `createdAt` unless you pass `sort`.\n\n**Required scope:** `report-charts:read`", "operationId": "listReportCharts", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `createdAt`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "projects", "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "dataType[eq]", "in": "query", "required": false, "description": "Filter where `dataType` equals.", "schema": { "type": "string", "enum": [ "live", "events", "historical" ] }, "example": "live" }, { "name": "chartType[eq]", "in": "query", "required": false, "description": "Filter where `chartType` equals.", "schema": { "type": "string", "enum": [ "line", "bar", "area", "areaStacked", "pie", "table", "number", "funnel" ] }, "example": "line" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/reportChartExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "Z3hEUMCq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Example", "projects": [ "iV6vIU8N" ] }, { "id": "5uGAameq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Second example", "projects": [ "iV6vIU8N" ] } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/report-charts\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/report-charts');" } ] }, "post": { "summary": "Create Report Chart", "description": "Create a Report Chart. Server-assigned fields are ignored if sent.\n\n**Required scope:** `report-charts:write`", "operationId": "createReportChart", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "projects", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reportChartCreate" }, "examples": { "default": { "value": { "projects": [ "iV6vIU8N" ], "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Example" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reportChartExpanded" }, "examples": { "default": { "value": { "id": "Z3hEUMCq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Example", "projects": [ "iV6vIU8N" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/report-charts\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"projects\":[\"iV6vIU8N\"],\"dataType\":\"live\",\"chartType\":\"line\",\"dateRange\":{},\"filter\":{},\"series\":[{\"metric\":\"count\",\"operator\":\"sum\",\"taskSet\":\"open_tasks\",\"color\":\"#00A99B\",\"name\":\"Open tasks\",\"filter\":{}}],\"name\":\"Example\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/report-charts', {\n body: {\n \"projects\": [\n \"iV6vIU8N\"\n ],\n \"dataType\": \"live\",\n \"chartType\": \"line\",\n \"dateRange\": {},\n \"filter\": {},\n \"series\": [\n {\n \"metric\": \"count\",\n \"operator\": \"sum\",\n \"taskSet\": \"open_tasks\",\n \"color\": \"#00A99B\",\n \"name\": \"Open tasks\",\n \"filter\": {}\n }\n ],\n \"name\": \"Example\"\n },\n});" } ] } }, "/report-charts/{id}": { "get": { "summary": "Get Report Chart", "description": "Retrieve a single Report Chart by id.\n\n**Required scope:** `report-charts:read`", "operationId": "getReportChart", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Report Chart.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Z3hEUMCq" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "projects", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reportChartExpanded" }, "examples": { "default": { "value": { "id": "Z3hEUMCq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Example", "projects": [ "iV6vIU8N" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/report-charts/Z3hEUMCq\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/report-charts/{id}', {\n params: { path: { id: 'Z3hEUMCq' } },\n});" } ] }, "patch": { "summary": "Update Report Chart", "description": "Partially update a Report Chart. Only the fields you send are changed.\n\n**Required scope:** `report-charts:write`", "operationId": "updateReportChart", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Report Chart.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Z3hEUMCq" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "projects", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "projects", "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reportChartUpdate" }, "examples": { "default": { "value": { "projects": [ "iV6vIU8N" ], "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Example", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reportChartExpanded" }, "examples": { "default": { "value": { "id": "Z3hEUMCq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "dataType": "live", "chartType": "line", "dateRange": {}, "filter": {}, "series": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "name": "Example", "projects": [ "iV6vIU8N" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/report-charts/Z3hEUMCq\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"projects\":[\"iV6vIU8N\"],\"dataType\":\"live\",\"chartType\":\"line\",\"dateRange\":{},\"filter\":{},\"series\":[{\"metric\":\"count\",\"operator\":\"sum\",\"taskSet\":\"open_tasks\",\"color\":\"#00A99B\",\"name\":\"Open tasks\",\"filter\":{}}],\"name\":\"Example\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/report-charts/{id}', {\n params: { path: { id: 'Z3hEUMCq' } },\n body: {\n \"projects\": [\n \"iV6vIU8N\"\n ],\n \"dataType\": \"live\",\n \"chartType\": \"line\",\n \"dateRange\": {},\n \"filter\": {},\n \"series\": [\n {\n \"metric\": \"count\",\n \"operator\": \"sum\",\n \"taskSet\": \"open_tasks\",\n \"color\": \"#00A99B\",\n \"name\": \"Open tasks\",\n \"filter\": {}\n }\n ],\n \"name\": \"Example\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Report Chart", "description": "Permanently delete this Report Chart. This cannot be undone.\n\n**Required scope:** `report-charts:delete`", "operationId": "deleteReportChart", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Report Chart.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Z3hEUMCq" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/report-charts/Z3hEUMCq\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/report-charts/{id}', {\n params: { path: { id: 'Z3hEUMCq' } },\n});" } ] } }, "/report-charts/{id}/projects": { "post": { "summary": "Add projects to a Report Chart", "description": "Link the given ids to this Report Chart as projects. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete projects set afterwards.\n\n**Required scopes:** `report-charts:write` `report-charts:link`", "operationId": "addReportChartProjects", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:write", "report-charts:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Report Chart.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Z3hEUMCq" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Projects to add or remove, by id.", "example": [ "iV6vIU8N", "QPw2r8rm" ] } } }, "examples": { "default": { "value": { "ids": [ "iV6vIU8N", "QPw2r8rm" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/project" }, "description": "The complete projects set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "iV6vIU8N" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } ], "affectedIds": [ "iV6vIU8N" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:write", "report-charts:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/report-charts/Z3hEUMCq/projects\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"iV6vIU8N\",\"QPw2r8rm\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/report-charts/{id}/projects', {\n params: { path: { id: 'Z3hEUMCq' } },\n body: {\n \"ids\": [\n \"iV6vIU8N\",\n \"QPw2r8rm\"\n ]\n },\n});" } ] } }, "/report-charts/{id}/projects/remove": { "post": { "summary": "Remove projects from a Report Chart", "description": "Unlink the given ids from this Report Chart's projects. Removing one that is not linked changes nothing. Returns the complete projects set afterwards.\n\n**Required scopes:** `report-charts:write` `report-charts:link`", "operationId": "removeReportChartProjects", "tags": [ "reportChart" ], "x-required-scopes": [ "report-charts:write", "report-charts:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Report Chart.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Z3hEUMCq" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Projects to add or remove, by id.", "example": [ "iV6vIU8N", "QPw2r8rm" ] } } }, "examples": { "default": { "value": { "ids": [ "iV6vIU8N", "QPw2r8rm" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/project" }, "description": "The complete projects set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "iV6vIU8N" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "iV6vIU8N", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "Enmkg49J", "archived": false, "niceId": "PRJ", "name": "Example", "description": "A concise description.", "icon": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "secondaryColor": "#0E7C74", "portfolioId": "1YEYsy2X", "accessType": "public", "modules": [ "home" ], "defaultTasksView": "table", "hiddenListColumns": [ "estimate", "labels" ], "listColumnsOrder": [ "name", "assignee", "dueDate" ], "customFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "taskCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "listCustomFieldsOrder": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "autoMilestones": false, "hideUsersFromGuests": false, "subtaskStatusEnabled": false, "queryAllFiles": false, "projectFolderId": "0sSAIGwG", "ownerId": "QpCuKyI2", "discussionChatId": "lNAaW0F4", "defaultStatusId": "O9nWOgic" } ], "affectedIds": [ "iV6vIU8N" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "report-charts:write", "report-charts:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/report-charts/Z3hEUMCq/projects/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"iV6vIU8N\",\"QPw2r8rm\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/report-charts/{id}/projects/remove', {\n params: { path: { id: 'Z3hEUMCq' } },\n body: {\n \"ids\": [\n \"iV6vIU8N\",\n \"QPw2r8rm\"\n ]\n },\n});" } ] } }, "/roles": { "get": { "summary": "List Roles", "description": "List roles. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by `name` unless you pass `sort`.\n\n**Required scope:** `roles:read`", "operationId": "listRoles", "tags": [ "role" ], "x-required-scopes": [ "roles:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `name`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "name" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "editable[eq]", "in": "query", "required": false, "description": "Filter where `editable` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/roleExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" }, { "id": "lFQ25VUI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "roles:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/roles\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/roles');" } ] }, "post": { "summary": "Create Role", "description": "Create a Role. Server-assigned fields are ignored if sent.\n\n**Required scope:** `roles:write`", "operationId": "createRole", "tags": [ "role" ], "x-required-scopes": [ "roles:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/roleCreate" }, "examples": { "default": { "value": { "name": "Example", "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/roleExpanded" }, "examples": { "default": { "value": { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "roles:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/roles\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"permissions\":[\"createTask\",\"editTask\",\"viewAllTasks\"],\"initialScreen\":\"allTasks\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/roles', {\n body: {\n \"name\": \"Example\",\n \"permissions\": [\n \"createTask\",\n \"editTask\",\n \"viewAllTasks\"\n ],\n \"initialScreen\": \"allTasks\"\n },\n});" } ] } }, "/roles/{id}": { "get": { "summary": "Get Role", "description": "Retrieve a single Role by id.\n\n**Required scope:** `roles:read`", "operationId": "getRole", "tags": [ "role" ], "x-required-scopes": [ "roles:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Role.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "zngY4nUy" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/roleExpanded" }, "examples": { "default": { "value": { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "roles:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/roles/zngY4nUy\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/roles/{id}', {\n params: { path: { id: 'zngY4nUy' } },\n});" } ] }, "patch": { "summary": "Update Role", "description": "Partially update a Role. Only the fields you send are changed.\n\n**Required scope:** `roles:write`", "operationId": "updateRole", "tags": [ "role" ], "x-required-scopes": [ "roles:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Role.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "zngY4nUy" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/roleUpdate" }, "examples": { "default": { "value": { "name": "Example", "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/roleExpanded" }, "examples": { "default": { "value": { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "roles:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/roles/zngY4nUy\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"permissions\":[\"createTask\",\"editTask\",\"viewAllTasks\"],\"initialScreen\":\"allTasks\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/roles/{id}', {\n params: { path: { id: 'zngY4nUy' } },\n body: {\n \"name\": \"Example\",\n \"permissions\": [\n \"createTask\",\n \"editTask\",\n \"viewAllTasks\"\n ],\n \"initialScreen\": \"allTasks\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Role", "description": "Permanently delete this Role. This cannot be undone. There are four possible outcomes. A built-in role is refused with 403. A role still held by an active member is refused with 409 — reassign them first. On success, anyone previously removed from the team who still held the role is moved to `regular`; if the workspace has no `regular` role, the delete is refused with 409 instead.\n\n**Required scope:** `roles:delete`", "operationId": "deleteRole", "tags": [ "role" ], "x-required-scopes": [ "roles:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Role.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "zngY4nUy" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "roles:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/roles/zngY4nUy\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/roles/{id}', {\n params: { path: { id: 'zngY4nUy' } },\n});" } ] } }, "/roles/search": { "get": { "summary": "Search Roles", "description": "Full-text ranked search across roles. Ranked by relevance; pages are capped at 200 results. Filterable by 3 fields.\n\n**Required scope:** `roles:read`", "operationId": "searchRoles", "tags": [ "role" ], "x-required-scopes": [ "roles:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "editable[eq]", "in": "query", "required": false, "description": "Filter where `editable` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/roleExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" }, { "id": "lFQ25VUI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "roles:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/roles/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/roles/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/statuses": { "get": { "summary": "List Statuses", "description": "List statuses. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `statuses:read`", "operationId": "listStatuses", "tags": [ "status" ], "x-required-scopes": [ "statuses:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list statuses across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "order", "createdAt", "updatedAt", "-name", "-order", "-createdAt", "-updatedAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "project", "assignees", "hiddenFor", "list", "tasks", "recurringRules" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "project" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/statusExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "5aM4ncwI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" }, { "id": "5AqW89Bw", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "color": "#00A99B", "order": 101, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/statuses\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/statuses');" } ] }, "post": { "summary": "Create Status", "description": "Create a Status. Server-assigned fields are ignored if sent.\n\n**Required scope:** `statuses:write`", "operationId": "createStatus", "tags": [ "status" ], "x-required-scopes": [ "statuses:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "project", "assignees", "hiddenFor", "list", "tasks", "recurringRules" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "project" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusCreate" }, "examples": { "default": { "value": { "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "projectId": "iV6vIU8N" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusExpanded" }, "examples": { "default": { "value": { "id": "5aM4ncwI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/statuses\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"color\":\"#00A99B\",\"order\":100,\"archived\":false,\"projectId\":\"iV6vIU8N\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/statuses', {\n body: {\n \"name\": \"Example\",\n \"color\": \"#00A99B\",\n \"order\": 100,\n \"archived\": false,\n \"projectId\": \"iV6vIU8N\"\n },\n});" } ] } }, "/statuses/{id}": { "get": { "summary": "Get Status", "description": "Retrieve a single Status by id.\n\n**Required scope:** `statuses:read`", "operationId": "getStatus", "tags": [ "status" ], "x-required-scopes": [ "statuses:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "project", "assignees", "hiddenFor", "list", "tasks", "recurringRules" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "project" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusExpanded" }, "examples": { "default": { "value": { "id": "5aM4ncwI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/statuses/{id}', {\n params: { path: { id: '5aM4ncwI' } },\n});" } ] }, "patch": { "summary": "Update Status", "description": "Partially update a Status. Only the fields you send are changed.\n\n**Required scope:** `statuses:write`", "operationId": "updateStatus", "tags": [ "status" ], "x-required-scopes": [ "statuses:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "project", "assignees", "hiddenFor", "list", "tasks", "recurringRules" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "project" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusUpdate" }, "examples": { "default": { "value": { "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/statusExpanded" }, "examples": { "default": { "value": { "id": "5aM4ncwI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"color\":\"#00A99B\",\"order\":100,\"archived\":false,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/statuses/{id}', {\n params: { path: { id: '5aM4ncwI' } },\n body: {\n \"name\": \"Example\",\n \"color\": \"#00A99B\",\n \"order\": 100,\n \"archived\": false,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Status", "description": "Permanently delete this Status. This cannot be undone.\n\n**Required scope:** `statuses:delete`", "operationId": "deleteStatus", "tags": [ "status" ], "x-required-scopes": [ "statuses:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/statuses/{id}', {\n params: { path: { id: '5aM4ncwI' } },\n});" } ] } }, "/statuses/search": { "get": { "summary": "Search Statuses", "description": "Full-text ranked search across statuses. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields.\n\n**Required scope:** `statuses:read`", "operationId": "searchStatuses", "tags": [ "status" ], "x-required-scopes": [ "statuses:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "projectId", "in": "query", "required": true, "description": "The project to search within. Required — statuses are project-scoped and search has no workspace-wide mode.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "project", "assignees", "hiddenFor", "list", "tasks", "recurringRules" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "project" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/statusExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "5aM4ncwI", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "color": "#00A99B", "order": 100, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" }, { "id": "5AqW89Bw", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Second example", "color": "#00A99B", "order": 101, "archived": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/statuses/search?q=design&projectId=iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/statuses/search', {\n params: { query: { q: 'design', projectId: 'iV6vIU8N' } },\n});" } ] } }, "/statuses/{id}/assignees": { "post": { "summary": "Add assignees to a Status", "description": "Link the given ids to this Status as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `statuses:write` `statuses:link`", "operationId": "addStatusAssignees", "tags": [ "status" ], "x-required-scopes": [ "statuses:write", "statuses:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:write", "statuses:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI/assignees\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/statuses/{id}/assignees', {\n params: { path: { id: '5aM4ncwI' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/statuses/{id}/assignees/remove": { "post": { "summary": "Remove assignees from a Status", "description": "Unlink the given ids from this Status's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `statuses:write` `statuses:link`", "operationId": "removeStatusAssignees", "tags": [ "status" ], "x-required-scopes": [ "statuses:write", "statuses:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:write", "statuses:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI/assignees/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/statuses/{id}/assignees/remove', {\n params: { path: { id: '5aM4ncwI' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/statuses/{id}/hidden-for": { "post": { "summary": "Add hidden for to a Status", "description": "Link the given ids to this Status as hiddenFor. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete hiddenFor set afterwards.\n\n**Required scopes:** `statuses:write` `statuses:link`", "operationId": "addStatusHiddenFor", "tags": [ "status" ], "x-required-scopes": [ "statuses:write", "statuses:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Roles to add or remove, by id.", "example": [ "zngY4nUy", "50hcKom2" ] } } }, "examples": { "default": { "value": { "ids": [ "zngY4nUy", "50hcKom2" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The complete hiddenFor set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "zngY4nUy" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "affectedIds": [ "zngY4nUy" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:write", "statuses:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI/hidden-for\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"zngY4nUy\",\"50hcKom2\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/statuses/{id}/hidden-for', {\n params: { path: { id: '5aM4ncwI' } },\n body: {\n \"ids\": [\n \"zngY4nUy\",\n \"50hcKom2\"\n ]\n },\n});" } ] } }, "/statuses/{id}/hidden-for/remove": { "post": { "summary": "Remove hidden for from a Status", "description": "Unlink the given ids from this Status's hiddenFor. Removing one that is not linked changes nothing. Returns the complete hiddenFor set afterwards.\n\n**Required scopes:** `statuses:write` `statuses:link`", "operationId": "removeStatusHiddenFor", "tags": [ "status" ], "x-required-scopes": [ "statuses:write", "statuses:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Status.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "5aM4ncwI" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Roles to add or remove, by id.", "example": [ "zngY4nUy", "50hcKom2" ] } } }, "examples": { "default": { "value": { "ids": [ "zngY4nUy", "50hcKom2" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The complete hiddenFor set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "zngY4nUy" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "affectedIds": [ "zngY4nUy" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "statuses:write", "statuses:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/statuses/5aM4ncwI/hidden-for/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"zngY4nUy\",\"50hcKom2\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/statuses/{id}/hidden-for/remove', {\n params: { path: { id: '5aM4ncwI' } },\n body: {\n \"ids\": [\n \"zngY4nUy\",\n \"50hcKom2\"\n ]\n },\n});" } ] } }, "/tasks": { "get": { "summary": "List Tasks", "description": "List tasks. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 22 fields. Ordered by `order` unless you pass `sort`.\n\n**Required scope:** `tasks:read`", "operationId": "listTasks", "tags": [ "task" ], "x-required-scopes": [ "tasks:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list tasks across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "scope", "in": "query", "required": false, "description": "Which tasks a workspace-wide list returns: `project` (rows that belong to a project you can access), `personal` (your own rows, which belong to no project), or `both`. Ignored when you pass `projectId`. Default: `both`.", "schema": { "type": "string", "enum": [ "both", "project", "personal" ] }, "example": "both" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `order`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "name", "niceId", "order", "orderList", "startAt", "dueAt", "createdAt", "updatedAt", "completedAt", "-name", "-niceId", "-order", "-orderList", "-startAt", "-dueAt", "-createdAt", "-updatedAt", "-completedAt" ] }, "example": "order" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "status", "list", "parentTask", "dependency", "recurringRule", "createdBy", "archivedBy", "completedBy", "createdByActor", "updatedByActor", "assignees", "labels", "subscribers", "hiddenFor", "connectedTasks", "subtasks", "messages", "checklists", "files", "customFields" ] } }, "style": "form", "explode": false, "example": [ "project", "status" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "niceId[eq]", "in": "query", "required": false, "description": "Filter where `niceId` equals.", "schema": { "type": "integer" }, "example": 1234 }, { "name": "niceId[in]", "in": "query", "required": false, "description": "Filter where `niceId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "integer" } }, "example": [ 1234, 1234 ] }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "completed[eq]", "in": "query", "required": false, "description": "Filter where `completed` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "listId[eq]", "in": "query", "required": false, "description": "Filter where `listId` equals.", "schema": { "type": "string" }, "example": "lN6ZQycO" }, { "name": "listId[in]", "in": "query", "required": false, "description": "Filter where `listId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "lN6ZQycO", "lN6ZQycO" ] }, { "name": "statusId[eq]", "in": "query", "required": false, "description": "Filter where `statusId` equals.", "schema": { "type": "string" }, "example": "5aM4ncwI" }, { "name": "statusId[in]", "in": "query", "required": false, "description": "Filter where `statusId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "5aM4ncwI", "5aM4ncwI" ] }, { "name": "parentTaskId[eq]", "in": "query", "required": false, "description": "Filter where `parentTaskId` equals.", "schema": { "type": "string" }, "example": "4KOocqYo" }, { "name": "parentTaskId[in]", "in": "query", "required": false, "description": "Filter where `parentTaskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "4KOocqYo", "4KOocqYo" ] }, { "name": "dependencyId[eq]", "in": "query", "required": false, "description": "Filter where `dependencyId` equals.", "schema": { "type": "string" }, "example": "i9TUmOWm" }, { "name": "dependencyId[in]", "in": "query", "required": false, "description": "Filter where `dependencyId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "i9TUmOWm", "i9TUmOWm" ] }, { "name": "recurringRuleId[eq]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` equals.", "schema": { "type": "string" }, "example": "cn2v0xiQ" }, { "name": "recurringRuleId[in]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "cn2v0xiQ", "cn2v0xiQ" ] }, { "name": "createdById[eq]", "in": "query", "required": false, "description": "Filter where `createdById` equals.", "schema": { "type": "string" }, "example": "njWQkGgk" }, { "name": "createdById[in]", "in": "query", "required": false, "description": "Filter where `createdById` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "njWQkGgk", "njWQkGgk" ] }, { "name": "labelId[eq]", "in": "query", "required": false, "description": "Filter where `labelId` equals.", "schema": { "type": "string" }, "example": "xbUMIqgS" }, { "name": "labelId[in]", "in": "query", "required": false, "description": "Filter where `labelId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "xbUMIqgS" ] }, { "name": "assigneeId[eq]", "in": "query", "required": false, "description": "Filter where `assigneeId` equals.", "schema": { "type": "string" }, "example": "CNIgSuay" }, { "name": "assigneeId[in]", "in": "query", "required": false, "description": "Filter where `assigneeId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "CNIgSuay" ] }, { "name": "subscriberId[eq]", "in": "query", "required": false, "description": "Filter where `subscriberId` equals.", "schema": { "type": "string" }, "example": "NlUEieKe" }, { "name": "subscriberId[in]", "in": "query", "required": false, "description": "Filter where `subscriberId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "NlUEieKe" ] }, { "name": "createdByActorId[eq]", "in": "query", "required": false, "description": "Filter where `createdByActorId` equals.", "schema": { "type": "string" }, "example": "49f861f7-4af8-44bf-844f-45f85babe504" }, { "name": "createdByActorId[in]", "in": "query", "required": false, "description": "Filter where `createdByActorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "49f861f7-4af8-44bf-844f-45f85babe504", "49f861f7-4af8-44bf-844f-45f85babe504" ] }, { "name": "updatedByActorId[eq]", "in": "query", "required": false, "description": "Filter where `updatedByActorId` equals.", "schema": { "type": "string" }, "example": "3306ed14-3606-4350-8300-2f06e6c80dce" }, { "name": "updatedByActorId[in]", "in": "query", "required": false, "description": "Filter where `updatedByActorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "3306ed14-3606-4350-8300-2f06e6c80dce", "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, { "name": "startAt[gt]", "in": "query", "required": false, "description": "Filter where `startAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "startAt[gte]", "in": "query", "required": false, "description": "Filter where `startAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "startAt[lt]", "in": "query", "required": false, "description": "Filter where `startAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "startAt[lte]", "in": "query", "required": false, "description": "Filter where `startAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "dueAt[gt]", "in": "query", "required": false, "description": "Filter where `dueAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "dueAt[gte]", "in": "query", "required": false, "description": "Filter where `dueAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "dueAt[lt]", "in": "query", "required": false, "description": "Filter where `dueAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "dueAt[lte]", "in": "query", "required": false, "description": "Filter where `dueAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "completedAt[gt]", "in": "query", "required": false, "description": "Filter where `completedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "completedAt[gte]", "in": "query", "required": false, "description": "Filter where `completedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "completedAt[lt]", "in": "query", "required": false, "description": "Filter where `completedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "completedAt[lte]", "in": "query", "required": false, "description": "Filter where `completedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "archivedAt[gt]", "in": "query", "required": false, "description": "Filter where `archivedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "archivedAt[gte]", "in": "query", "required": false, "description": "Filter where `archivedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "archivedAt[lt]", "in": "query", "required": false, "description": "Filter where `archivedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "archivedAt[lte]", "in": "query", "required": false, "description": "Filter where `archivedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/taskExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" }, { "id": "o9fSwokO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1235, "name": "Second example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 101, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/tasks\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/tasks');" } ] }, "post": { "summary": "Create Task", "description": "Create a Task. Server-assigned fields are ignored if sent.\n\n**Required scope:** `tasks:write`", "operationId": "createTask", "tags": [ "task" ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "status", "list", "parentTask", "dependency", "recurringRule", "createdBy", "archivedBy", "completedBy", "createdByActor", "updatedByActor", "assignees", "labels", "subscribers", "hiddenFor", "connectedTasks", "subtasks", "messages", "checklists", "files", "customFields" ] } }, "style": "form", "explode": false, "example": [ "project", "status" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskCreate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "archived": false, "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "customFields": [], "assignees": [ "CNIgSuay" ], "labels": [ "xbUMIqgS" ], "subscribers": [ "NlUEieKe" ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskExpanded" }, "examples": { "default": { "value": { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"archived\":false,\"completed\":false,\"projectId\":\"iV6vIU8N\",\"listId\":\"lN6ZQycO\",\"statusId\":\"5aM4ncwI\",\"parentTaskId\":\"4KOocqYo\",\"dependencyId\":\"i9TUmOWm\",\"recurringRuleId\":\"cn2v0xiQ\",\"startAt\":\"2026-06-01T12:00:00.000Z\",\"dueAt\":\"2026-06-07T12:00:00.000Z\",\"remindAt\":\"2026-06-04T02:00:00.000Z\",\"storyPoints\":100,\"order\":100,\"orderList\":100,\"banner\":\"https://cdn.nifty.pm/example.png\",\"embedUrl\":\"https://example.com/resource\",\"customFields\":[],\"assignees\":[\"CNIgSuay\"],\"labels\":[\"xbUMIqgS\"],\"subscribers\":[\"NlUEieKe\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"archived\": false,\n \"completed\": false,\n \"projectId\": \"iV6vIU8N\",\n \"listId\": \"lN6ZQycO\",\n \"statusId\": \"5aM4ncwI\",\n \"parentTaskId\": \"4KOocqYo\",\n \"dependencyId\": \"i9TUmOWm\",\n \"recurringRuleId\": \"cn2v0xiQ\",\n \"startAt\": \"2026-06-01T12:00:00.000Z\",\n \"dueAt\": \"2026-06-07T12:00:00.000Z\",\n \"remindAt\": \"2026-06-04T02:00:00.000Z\",\n \"storyPoints\": 100,\n \"order\": 100,\n \"orderList\": 100,\n \"banner\": \"https://cdn.nifty.pm/example.png\",\n \"embedUrl\": \"https://example.com/resource\",\n \"customFields\": [],\n \"assignees\": [\n \"CNIgSuay\"\n ],\n \"labels\": [\n \"xbUMIqgS\"\n ],\n \"subscribers\": [\n \"NlUEieKe\"\n ]\n },\n});" } ] } }, "/tasks/{id}": { "get": { "summary": "Get Task", "description": "Retrieve a single Task by id.\n\n**Required scope:** `tasks:read`", "operationId": "getTask", "tags": [ "task" ], "x-required-scopes": [ "tasks:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "status", "list", "parentTask", "dependency", "recurringRule", "createdBy", "archivedBy", "completedBy", "createdByActor", "updatedByActor", "assignees", "labels", "subscribers", "hiddenFor", "connectedTasks", "subtasks", "messages", "checklists", "files", "customFields" ] } }, "style": "form", "explode": false, "example": [ "project", "status" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskExpanded" }, "examples": { "default": { "value": { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/tasks/{id}', {\n params: { path: { id: 'KfS0ha8P' } },\n});" } ] }, "patch": { "summary": "Update Task", "description": "Partially update a Task. Only the fields you send are changed.\n\n**Required scope:** `tasks:write`", "operationId": "updateTask", "tags": [ "task" ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "status", "list", "parentTask", "dependency", "recurringRule", "createdBy", "archivedBy", "completedBy", "createdByActor", "updatedByActor", "assignees", "labels", "subscribers", "hiddenFor", "connectedTasks", "subtasks", "messages", "checklists", "files", "customFields" ] } }, "style": "form", "explode": false, "example": [ "project", "status" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskUpdate" }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "archived": false, "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "customFields": [], "assignees": [ "CNIgSuay" ], "labels": [ "xbUMIqgS" ], "subscribers": [ "NlUEieKe" ], "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskExpanded" }, "examples": { "default": { "value": { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"archived\":false,\"completed\":false,\"projectId\":\"iV6vIU8N\",\"listId\":\"lN6ZQycO\",\"statusId\":\"5aM4ncwI\",\"parentTaskId\":\"4KOocqYo\",\"dependencyId\":\"i9TUmOWm\",\"recurringRuleId\":\"cn2v0xiQ\",\"startAt\":\"2026-06-01T12:00:00.000Z\",\"dueAt\":\"2026-06-07T12:00:00.000Z\",\"remindAt\":\"2026-06-04T02:00:00.000Z\",\"storyPoints\":100,\"order\":100,\"orderList\":100,\"banner\":\"https://cdn.nifty.pm/example.png\",\"embedUrl\":\"https://example.com/resource\",\"customFields\":[],\"assignees\":[\"CNIgSuay\"],\"labels\":[\"xbUMIqgS\"],\"subscribers\":[\"NlUEieKe\"],\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/tasks/{id}', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"archived\": false,\n \"completed\": false,\n \"projectId\": \"iV6vIU8N\",\n \"listId\": \"lN6ZQycO\",\n \"statusId\": \"5aM4ncwI\",\n \"parentTaskId\": \"4KOocqYo\",\n \"dependencyId\": \"i9TUmOWm\",\n \"recurringRuleId\": \"cn2v0xiQ\",\n \"startAt\": \"2026-06-01T12:00:00.000Z\",\n \"dueAt\": \"2026-06-07T12:00:00.000Z\",\n \"remindAt\": \"2026-06-04T02:00:00.000Z\",\n \"storyPoints\": 100,\n \"order\": 100,\n \"orderList\": 100,\n \"banner\": \"https://cdn.nifty.pm/example.png\",\n \"embedUrl\": \"https://example.com/resource\",\n \"customFields\": [],\n \"assignees\": [\n \"CNIgSuay\"\n ],\n \"labels\": [\n \"xbUMIqgS\"\n ],\n \"subscribers\": [\n \"NlUEieKe\"\n ],\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Task", "description": "Permanently delete this Task. This cannot be undone.\n\n**Required scope:** `tasks:delete`", "operationId": "deleteTask", "tags": [ "task" ], "x-required-scopes": [ "tasks:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/tasks/{id}', {\n params: { path: { id: 'KfS0ha8P' } },\n});" } ] } }, "/tasks/search": { "get": { "summary": "Search Tasks", "description": "Full-text ranked search across tasks. Ranked by relevance; pages are capped at 200 results. Filterable by 22 fields.\n\n**Required scope:** `tasks:read`", "operationId": "searchTasks", "tags": [ "task" ], "x-required-scopes": [ "tasks:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "projectId", "in": "query", "required": true, "description": "The project to search within. Required — tasks are project-scoped and search has no workspace-wide mode.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "project", "status", "list", "parentTask", "dependency", "recurringRule", "createdBy", "archivedBy", "completedBy", "createdByActor", "updatedByActor", "assignees", "labels", "subscribers", "hiddenFor", "connectedTasks", "subtasks", "messages", "checklists", "files", "customFields" ] } }, "style": "form", "explode": false, "example": [ "project", "status" ] }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "niceId[eq]", "in": "query", "required": false, "description": "Filter where `niceId` equals.", "schema": { "type": "integer" }, "example": 1234 }, { "name": "niceId[in]", "in": "query", "required": false, "description": "Filter where `niceId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "integer" } }, "example": [ 1234, 1234 ] }, { "name": "archived[eq]", "in": "query", "required": false, "description": "Filter where `archived` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "completed[eq]", "in": "query", "required": false, "description": "Filter where `completed` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "listId[eq]", "in": "query", "required": false, "description": "Filter where `listId` equals.", "schema": { "type": "string" }, "example": "lN6ZQycO" }, { "name": "listId[in]", "in": "query", "required": false, "description": "Filter where `listId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "lN6ZQycO", "lN6ZQycO" ] }, { "name": "statusId[eq]", "in": "query", "required": false, "description": "Filter where `statusId` equals.", "schema": { "type": "string" }, "example": "5aM4ncwI" }, { "name": "statusId[in]", "in": "query", "required": false, "description": "Filter where `statusId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "5aM4ncwI", "5aM4ncwI" ] }, { "name": "parentTaskId[eq]", "in": "query", "required": false, "description": "Filter where `parentTaskId` equals.", "schema": { "type": "string" }, "example": "4KOocqYo" }, { "name": "parentTaskId[in]", "in": "query", "required": false, "description": "Filter where `parentTaskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "4KOocqYo", "4KOocqYo" ] }, { "name": "dependencyId[eq]", "in": "query", "required": false, "description": "Filter where `dependencyId` equals.", "schema": { "type": "string" }, "example": "i9TUmOWm" }, { "name": "dependencyId[in]", "in": "query", "required": false, "description": "Filter where `dependencyId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "i9TUmOWm", "i9TUmOWm" ] }, { "name": "recurringRuleId[eq]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` equals.", "schema": { "type": "string" }, "example": "cn2v0xiQ" }, { "name": "recurringRuleId[in]", "in": "query", "required": false, "description": "Filter where `recurringRuleId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "cn2v0xiQ", "cn2v0xiQ" ] }, { "name": "createdById[eq]", "in": "query", "required": false, "description": "Filter where `createdById` equals.", "schema": { "type": "string" }, "example": "njWQkGgk" }, { "name": "createdById[in]", "in": "query", "required": false, "description": "Filter where `createdById` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "njWQkGgk", "njWQkGgk" ] }, { "name": "labelId[eq]", "in": "query", "required": false, "description": "Filter where `labelId` equals.", "schema": { "type": "string" }, "example": "xbUMIqgS" }, { "name": "labelId[in]", "in": "query", "required": false, "description": "Filter where `labelId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "xbUMIqgS" ] }, { "name": "assigneeId[eq]", "in": "query", "required": false, "description": "Filter where `assigneeId` equals.", "schema": { "type": "string" }, "example": "CNIgSuay" }, { "name": "assigneeId[in]", "in": "query", "required": false, "description": "Filter where `assigneeId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "CNIgSuay" ] }, { "name": "subscriberId[eq]", "in": "query", "required": false, "description": "Filter where `subscriberId` equals.", "schema": { "type": "string" }, "example": "NlUEieKe" }, { "name": "subscriberId[in]", "in": "query", "required": false, "description": "Filter where `subscriberId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "NlUEieKe" ] }, { "name": "createdByActorId[eq]", "in": "query", "required": false, "description": "Filter where `createdByActorId` equals.", "schema": { "type": "string" }, "example": "49f861f7-4af8-44bf-844f-45f85babe504" }, { "name": "createdByActorId[in]", "in": "query", "required": false, "description": "Filter where `createdByActorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "49f861f7-4af8-44bf-844f-45f85babe504", "49f861f7-4af8-44bf-844f-45f85babe504" ] }, { "name": "updatedByActorId[eq]", "in": "query", "required": false, "description": "Filter where `updatedByActorId` equals.", "schema": { "type": "string" }, "example": "3306ed14-3606-4350-8300-2f06e6c80dce" }, { "name": "updatedByActorId[in]", "in": "query", "required": false, "description": "Filter where `updatedByActorId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "3306ed14-3606-4350-8300-2f06e6c80dce", "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, { "name": "startAt[gt]", "in": "query", "required": false, "description": "Filter where `startAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "startAt[gte]", "in": "query", "required": false, "description": "Filter where `startAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "startAt[lt]", "in": "query", "required": false, "description": "Filter where `startAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "startAt[lte]", "in": "query", "required": false, "description": "Filter where `startAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "dueAt[gt]", "in": "query", "required": false, "description": "Filter where `dueAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "dueAt[gte]", "in": "query", "required": false, "description": "Filter where `dueAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "dueAt[lt]", "in": "query", "required": false, "description": "Filter where `dueAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "dueAt[lte]", "in": "query", "required": false, "description": "Filter where `dueAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-07T12:00:00.000Z" }, { "name": "completedAt[gt]", "in": "query", "required": false, "description": "Filter where `completedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "completedAt[gte]", "in": "query", "required": false, "description": "Filter where `completedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "completedAt[lt]", "in": "query", "required": false, "description": "Filter where `completedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "completedAt[lte]", "in": "query", "required": false, "description": "Filter where `completedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-03T12:00:00.000Z" }, { "name": "archivedAt[gt]", "in": "query", "required": false, "description": "Filter where `archivedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "archivedAt[gte]", "in": "query", "required": false, "description": "Filter where `archivedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "archivedAt[lt]", "in": "query", "required": false, "description": "Filter where `archivedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "archivedAt[lte]", "in": "query", "required": false, "description": "Filter where `archivedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-05T12:00:00.000Z" }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "updatedAt[gt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[gte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lt]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" }, { "name": "updatedAt[lte]", "in": "query", "required": false, "description": "Filter where `updatedAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T14:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/taskExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" }, { "id": "o9fSwokO", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1235, "name": "Second example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 101, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/tasks/search?q=design&projectId=iV6vIU8N\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/tasks/search', {\n params: { query: { q: 'design', projectId: 'iV6vIU8N' } },\n});" } ] } }, "/tasks/{id}/assignees": { "post": { "summary": "Add assignees to a Task", "description": "Link the given ids to this Task as assignees. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "addTaskAssignees", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/assignees\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/assignees', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/tasks/{id}/assignees/remove": { "post": { "summary": "Remove assignees from a Task", "description": "Unlink the given ids from this Task's assignees. Removing one that is not linked changes nothing. Returns the complete assignees set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "removeTaskAssignees", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete assignees set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/assignees/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/assignees/remove', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/tasks/{id}/labels": { "post": { "summary": "Add labels to a Task", "description": "Link the given ids to this Task as labels. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete labels set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "addTaskLabels", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Labels to add or remove, by id.", "example": [ "xbUMIqgS", "rXYsOME8" ] } } }, "examples": { "default": { "value": { "ids": [ "xbUMIqgS", "rXYsOME8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The complete labels set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "xbUMIqgS" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } ], "affectedIds": [ "xbUMIqgS" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/labels\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"xbUMIqgS\",\"rXYsOME8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/labels', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"xbUMIqgS\",\n \"rXYsOME8\"\n ]\n },\n});" } ] } }, "/tasks/{id}/labels/remove": { "post": { "summary": "Remove labels from a Task", "description": "Unlink the given ids from this Task's labels. Removing one that is not linked changes nothing. Returns the complete labels set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "removeTaskLabels", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Labels to add or remove, by id.", "example": [ "xbUMIqgS", "rXYsOME8" ] } } }, "examples": { "default": { "value": { "ids": [ "xbUMIqgS", "rXYsOME8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The complete labels set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "xbUMIqgS" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "xbUMIqgS", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "7ESqMCCu", "name": "Example", "color": "#00A99B", "default": false, "type": "others" } ], "affectedIds": [ "xbUMIqgS" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/labels/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"xbUMIqgS\",\"rXYsOME8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/labels/remove', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"xbUMIqgS\",\n \"rXYsOME8\"\n ]\n },\n});" } ] } }, "/tasks/{id}/subscribers": { "post": { "summary": "Add subscribers to a Task", "description": "Link the given ids to this Task as subscribers. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete subscribers set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "addTaskSubscribers", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete subscribers set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "P3hYIKqK" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/subscribers\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/subscribers', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/tasks/{id}/subscribers/remove": { "post": { "summary": "Remove subscribers from a Task", "description": "Unlink the given ids from this Task's subscribers. Removing one that is not linked changes nothing. Returns the complete subscribers set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "removeTaskSubscribers", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Team Members to add or remove, by id.", "example": [ "P3hYIKqK", "nvgG0jMq" ] } } }, "examples": { "default": { "value": { "ids": [ "P3hYIKqK", "nvgG0jMq" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The complete subscribers set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "P3hYIKqK" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "P3hYIKqK", "userId": "EF6LMc0F", "name": "Example", "email": "jane@acme.com", "avatar": "https://cdn.nifty.pm/example.png", "initials": "NB", "color": "#00A99B", "online": false, "tzIana": "America/New_York", "pending": false, "removed": false, "roleId": "zngY4nUy", "theme": "light", "storyPointsCapacity": 100 } ], "affectedIds": [ "P3hYIKqK" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/subscribers/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"P3hYIKqK\",\"nvgG0jMq\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/subscribers/remove', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"P3hYIKqK\",\n \"nvgG0jMq\"\n ]\n },\n});" } ] } }, "/tasks/{id}/hidden-for": { "post": { "summary": "Add hidden for to a Task", "description": "Link the given ids to this Task as hiddenFor. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete hiddenFor set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "addTaskHiddenFor", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Roles to add or remove, by id.", "example": [ "zngY4nUy", "50hcKom2" ] } } }, "examples": { "default": { "value": { "ids": [ "zngY4nUy", "50hcKom2" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The complete hiddenFor set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "zngY4nUy" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "affectedIds": [ "zngY4nUy" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/hidden-for\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"zngY4nUy\",\"50hcKom2\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/hidden-for', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"zngY4nUy\",\n \"50hcKom2\"\n ]\n },\n});" } ] } }, "/tasks/{id}/hidden-for/remove": { "post": { "summary": "Remove hidden for from a Task", "description": "Unlink the given ids from this Task's hiddenFor. Removing one that is not linked changes nothing. Returns the complete hiddenFor set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "removeTaskHiddenFor", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Roles to add or remove, by id.", "example": [ "zngY4nUy", "50hcKom2" ] } } }, "examples": { "default": { "value": { "ids": [ "zngY4nUy", "50hcKom2" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The complete hiddenFor set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "zngY4nUy" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "zngY4nUy", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "name": "Example", "editable": false, "permissions": [ "createTask", "editTask", "viewAllTasks" ], "initialScreen": "allTasks" } ], "affectedIds": [ "zngY4nUy" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/hidden-for/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"zngY4nUy\",\"50hcKom2\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/hidden-for/remove', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"zngY4nUy\",\n \"50hcKom2\"\n ]\n },\n});" } ] } }, "/tasks/{id}/connected-tasks": { "post": { "summary": "Add connected tasks to a Task", "description": "Link the given ids to this Task as connectedTasks. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete connectedTasks set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "addTaskConnectedTasks", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Tasks to add or remove, by id.", "example": [ "KfS0ha8P", "AfOKgoI8" ] } } }, "examples": { "default": { "value": { "ids": [ "KfS0ha8P", "AfOKgoI8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The complete connectedTasks set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually linked (ones already linked are omitted).", "example": [ "KfS0ha8P" ] }, "missingIds": { "type": "array", "items": { "type": "string" }, "description": "Ids you sent that do not exist or are not visible to this token.", "example": [] } } }, "examples": { "default": { "value": { "data": [ { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } ], "affectedIds": [ "KfS0ha8P" ], "missingIds": [] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/connected-tasks\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"KfS0ha8P\",\"AfOKgoI8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/connected-tasks', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"KfS0ha8P\",\n \"AfOKgoI8\"\n ]\n },\n});" } ] } }, "/tasks/{id}/connected-tasks/remove": { "post": { "summary": "Remove connected tasks from a Task", "description": "Unlink the given ids from this Task's connectedTasks. Removing one that is not linked changes nothing. Returns the complete connectedTasks set afterwards.\n\n**Required scopes:** `tasks:write` `tasks:link`", "operationId": "removeTaskConnectedTasks", "tags": [ "task" ], "x-required-scopes": [ "tasks:write", "tasks:link" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Tasks to add or remove, by id.", "example": [ "KfS0ha8P", "AfOKgoI8" ] } } }, "examples": { "default": { "value": { "ids": [ "KfS0ha8P", "AfOKgoI8" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "affectedIds" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The complete connectedTasks set after the change." }, "affectedIds": { "type": "array", "items": { "type": "string" }, "description": "The ids that were actually unlinked (ones not linked are omitted).", "example": [ "KfS0ha8P" ] } } }, "examples": { "default": { "value": { "data": [ { "id": "KfS0ha8P", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "archived": false, "niceId": 1234, "name": "Example", "description": "A concise description.", "completed": false, "projectId": "iV6vIU8N", "listId": "lN6ZQycO", "statusId": "5aM4ncwI", "parentTaskId": "4KOocqYo", "dependencyId": "i9TUmOWm", "recurringRuleId": "cn2v0xiQ", "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "remindAt": "2026-06-04T02:00:00.000Z", "storyPoints": 100, "order": 100, "orderList": 100, "banner": "https://cdn.nifty.pm/example.png", "embedUrl": "https://example.com/resource", "createdById": "njWQkGgk" } ], "affectedIds": [ "KfS0ha8P" ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write", "tasks:link" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/connected-tasks/remove\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\":[\"KfS0ha8P\",\"AfOKgoI8\"]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/connected-tasks/remove', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"ids\": [\n \"KfS0ha8P\",\n \"AfOKgoI8\"\n ]\n },\n});" } ] } }, "/tasks/create-tree": { "post": { "summary": "Create tree (Task)", "description": "Create a task with its subtasks and their checklists in one atomic call — no id-threading, no half-built trees.\n\n**Required scope:** `tasks:write`", "operationId": "createTreeTasks", "tags": [ "task" ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "niceId": { "type": "number" }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "itemIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "itemIds" ], "additionalProperties": false } } }, "required": [ "id", "checklists" ], "additionalProperties": false } } }, "required": [ "id", "niceId", "subtasks" ], "additionalProperties": false }, "examples": { "default": { "value": { "id": "XXKmAKg6", "niceId": 1234, "subtasks": [ { "id": "XXKmAKg6", "checklists": [ { "id": "XXKmAKg6", "itemIds": [ "Example item ids" ] } ] } ] } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "startAt": { "type": "string", "format": "date-time" }, "dueAt": { "type": "string", "format": "date-time" }, "completed": { "type": "boolean" }, "statusId": { "type": "string", "minLength": 1 }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50 }, "projectId": { "type": "string", "minLength": 1 }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "startAt": { "type": "string", "format": "date-time" }, "dueAt": { "type": "string", "format": "date-time" }, "completed": { "type": "boolean" }, "statusId": { "type": "string", "minLength": 1 }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50 }, "checklists": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 } }, "required": [ "items" ], "additionalProperties": false }, "maxItems": 20 } }, "required": [ "name" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "name", "projectId" ], "additionalProperties": false }, "examples": { "default": { "value": { "name": "Example", "description": "A concise description.", "assignees": [ "Example assignees" ], "labels": [ "Example labels" ], "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "completed": false, "statusId": "5aM4ncwI", "customFields": [ { "customFieldId": "6GWCcskG", "value": "Example value" } ], "projectId": "iV6vIU8N", "subtasks": [ { "name": "Example", "description": "A concise description.", "assignees": [ "Example assignees" ], "labels": [ "Example labels" ], "startAt": "2026-06-01T12:00:00.000Z", "dueAt": "2026-06-07T12:00:00.000Z", "completed": false, "statusId": "5aM4ncwI", "customFields": [ { "customFieldId": "6GWCcskG", "value": "Example value" } ], "checklists": [ { "name": "Example", "items": [ "Example items" ] } ] } ] } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/create-tree\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"description\":\"A concise description.\",\"assignees\":[\"Example assignees\"],\"labels\":[\"Example labels\"],\"startAt\":\"2026-06-01T12:00:00.000Z\",\"dueAt\":\"2026-06-07T12:00:00.000Z\",\"completed\":false,\"statusId\":\"5aM4ncwI\",\"customFields\":[{\"customFieldId\":\"6GWCcskG\",\"value\":\"Example value\"}],\"projectId\":\"iV6vIU8N\",\"subtasks\":[{\"name\":\"Example\",\"description\":\"A concise description.\",\"assignees\":[\"Example assignees\"],\"labels\":[\"Example labels\"],\"startAt\":\"2026-06-01T12:00:00.000Z\",\"dueAt\":\"2026-06-07T12:00:00.000Z\",\"completed\":false,\"statusId\":\"5aM4ncwI\",\"customFields\":[{\"customFieldId\":\"6GWCcskG\",\"value\":\"Example value\"}],\"checklists\":[{\"name\":\"Example\",\"items\":[\"Example items\"]}]}]}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/create-tree', {\n body: {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"assignees\": [\n \"Example assignees\"\n ],\n \"labels\": [\n \"Example labels\"\n ],\n \"startAt\": \"2026-06-01T12:00:00.000Z\",\n \"dueAt\": \"2026-06-07T12:00:00.000Z\",\n \"completed\": false,\n \"statusId\": \"5aM4ncwI\",\n \"customFields\": [\n {\n \"customFieldId\": \"6GWCcskG\",\n \"value\": \"Example value\"\n }\n ],\n \"projectId\": \"iV6vIU8N\",\n \"subtasks\": [\n {\n \"name\": \"Example\",\n \"description\": \"A concise description.\",\n \"assignees\": [\n \"Example assignees\"\n ],\n \"labels\": [\n \"Example labels\"\n ],\n \"startAt\": \"2026-06-01T12:00:00.000Z\",\n \"dueAt\": \"2026-06-07T12:00:00.000Z\",\n \"completed\": false,\n \"statusId\": \"5aM4ncwI\",\n \"customFields\": [\n {\n \"customFieldId\": \"6GWCcskG\",\n \"value\": \"Example value\"\n }\n ],\n \"checklists\": [\n {\n \"name\": \"Example\",\n \"items\": [\n \"Example items\"\n ]\n }\n ]\n }\n ]\n },\n});" } ] } }, "/tasks/{id}/attach-document": { "post": { "summary": "Attach document (Task)", "description": "Attach an existing document to this task (id = the task, documentId = the document; both must already exist in the same workspace). Idempotent — re-attaching is a no-op. Task assignees gain access to the document.\n\n**Required scope:** `tasks:write`", "operationId": "attachDocumentTask", "tags": [ "task" ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 } }, "required": [ "taskId", "documentId" ], "additionalProperties": false }, "examples": { "default": { "value": { "taskId": "KfS0ha8P", "documentId": "ELe0nkum" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1 } }, "required": [ "documentId" ], "additionalProperties": false }, "examples": { "default": { "value": { "documentId": "ELe0nkum" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/attach-document\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"documentId\":\"ELe0nkum\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/attach-document', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"documentId\": \"ELe0nkum\"\n },\n});" } ] } }, "/tasks/{id}/detach-document": { "post": { "summary": "Detach document (Task)", "description": "Detach a previously attached document from this task (id = the task, documentId = the document). Idempotent.\n\n**Required scope:** `tasks:write`", "operationId": "detachDocumentTask", "tags": [ "task" ], "x-required-scopes": [ "tasks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Task.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "KfS0ha8P" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 } }, "required": [ "taskId", "documentId" ], "additionalProperties": false }, "examples": { "default": { "value": { "taskId": "KfS0ha8P", "documentId": "ELe0nkum" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "tasks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1 } }, "required": [ "documentId" ], "additionalProperties": false }, "examples": { "default": { "value": { "documentId": "ELe0nkum" } } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/tasks/KfS0ha8P/detach-document\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"documentId\":\"ELe0nkum\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/tasks/{id}/detach-document', {\n params: { path: { id: 'KfS0ha8P' } },\n body: {\n \"documentId\": \"ELe0nkum\"\n },\n});" } ] } }, "/task-handoffs": { "get": { "summary": "List Handoffs", "description": "List taskHandoffs. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 3 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `task-handoffs:read`", "operationId": "listTaskHandoffs", "tags": [ "taskHandoff" ], "x-required-scopes": [ "task-handoffs:read" ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Restrict the list to one project. Omit to list taskHandoffs across every project you can access.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`. Listing without `projectId` orders by `-updatedAt` instead.", "schema": { "type": "string", "enum": [ "createdAt", "-createdAt" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "schema[eq]", "in": "query", "required": false, "description": "Filter where `schema` equals.", "schema": { "type": "string" }, "example": "nifty.checkpoint/1" }, { "name": "schema[in]", "in": "query", "required": false, "description": "Filter where `schema` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "nifty.checkpoint/1", "nifty.checkpoint/1" ] }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/taskHandoffExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "Ef8f2Vmq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "taskId": "KfS0ha8P", "schema": "nifty.checkpoint/1", "summary": "build → pass · next: open the PR against main", "body": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } }, { "id": "M1xO0PMi", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "taskId": "KfS0ha8P", "schema": "nifty.checkpoint/1", "summary": "build → pass · next: open the PR against main", "body": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "task-handoffs:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/task-handoffs\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/task-handoffs');" } ] }, "post": { "summary": "Create Handoff", "description": "Create a Handoff. Server-assigned fields are ignored if sent.\n\n**Required scope:** `task-handoffs:write`", "operationId": "createTaskHandoff", "tags": [ "taskHandoff" ], "x-required-scopes": [ "task-handoffs:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskHandoffCreate" }, "examples": { "default": { "value": { "taskId": "KfS0ha8P", "summary": "build → pass · next: open the PR against main", "body": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskHandoffExpanded" }, "examples": { "default": { "value": { "id": "Ef8f2Vmq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "taskId": "KfS0ha8P", "schema": "nifty.checkpoint/1", "summary": "build → pass · next: open the PR against main", "body": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "task-handoffs:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/task-handoffs\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"taskId\":\"KfS0ha8P\",\"summary\":\"build → pass · next: open the PR against main\",\"body\":{\"schema\":\"nifty.checkpoint/1\",\"requirements\":{\"source\":\"card description\",\"acceptanceCriteria\":[\"the export downloads as CSV\"]},\"invariantRegister\":[\"never write to the production replica\"],\"decisions\":[{\"decision\":\"stream the CSV instead of buffering it\",\"reason\":\"exports above 50k rows ran out of memory\"}],\"hypothesesEvaluated\":[{\"idea\":\"raise the worker memory limit\",\"result\":\"rejected — hides the bug at 100k rows\"}],\"deltaState\":{\"filesModified\":[\"src/export/csv.service.ts\"],\"checksRun\":[{\"cmd\":\"npm test -- csv\",\"revision\":\"a1b2c3d\",\"result\":\"12 passed\"}]},\"openQuestions\":[\"should the export include archived rows?\"],\"executionPointer\":{\"nextAction\":\"open the PR and request review\",\"blockedBy\":\"the streaming change must merge first\"},\"repos\":[{\"name\":\"api\",\"sha\":\"a1b2c3d\",\"branch\":\"feat/csv-export\",\"pushed\":true,\"dirty\":false}],\"writer\":{\"tool\":\"claude-code\"},\"precededBy\":\"thNfB2k9\"}}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/task-handoffs', {\n body: {\n \"taskId\": \"KfS0ha8P\",\n \"summary\": \"build → pass · next: open the PR against main\",\n \"body\": {\n \"schema\": \"nifty.checkpoint/1\",\n \"requirements\": {\n \"source\": \"card description\",\n \"acceptanceCriteria\": [\n \"the export downloads as CSV\"\n ]\n },\n \"invariantRegister\": [\n \"never write to the production replica\"\n ],\n \"decisions\": [\n {\n \"decision\": \"stream the CSV instead of buffering it\",\n \"reason\": \"exports above 50k rows ran out of memory\"\n }\n ],\n \"hypothesesEvaluated\": [\n {\n \"idea\": \"raise the worker memory limit\",\n \"result\": \"rejected — hides the bug at 100k rows\"\n }\n ],\n \"deltaState\": {\n \"filesModified\": [\n \"src/export/csv.service.ts\"\n ],\n \"checksRun\": [\n {\n \"cmd\": \"npm test -- csv\",\n \"revision\": \"a1b2c3d\",\n \"result\": \"12 passed\"\n }\n ]\n },\n \"openQuestions\": [\n \"should the export include archived rows?\"\n ],\n \"executionPointer\": {\n \"nextAction\": \"open the PR and request review\",\n \"blockedBy\": \"the streaming change must merge first\"\n },\n \"repos\": [\n {\n \"name\": \"api\",\n \"sha\": \"a1b2c3d\",\n \"branch\": \"feat/csv-export\",\n \"pushed\": true,\n \"dirty\": false\n }\n ],\n \"writer\": {\n \"tool\": \"claude-code\"\n },\n \"precededBy\": \"thNfB2k9\"\n }\n },\n});" } ] } }, "/task-handoffs/{id}": { "get": { "summary": "Get Handoff", "description": "Retrieve a single Handoff by id.\n\n**Required scope:** `task-handoffs:read`", "operationId": "getTaskHandoff", "tags": [ "taskHandoff" ], "x-required-scopes": [ "task-handoffs:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Handoff.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Ef8f2Vmq" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "task", "createdByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskHandoffExpanded" }, "examples": { "default": { "value": { "id": "Ef8f2Vmq", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "taskId": "KfS0ha8P", "schema": "nifty.checkpoint/1", "summary": "build → pass · next: open the PR against main", "body": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "task-handoffs:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/task-handoffs/Ef8f2Vmq\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/task-handoffs/{id}', {\n params: { path: { id: 'Ef8f2Vmq' } },\n});" } ] }, "delete": { "summary": "Delete Handoff", "description": "Permanently delete this Handoff. This cannot be undone.\n\n**Required scope:** `task-handoffs:delete`", "operationId": "deleteTaskHandoff", "tags": [ "taskHandoff" ], "x-required-scopes": [ "task-handoffs:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Handoff.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "Ef8f2Vmq" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "task-handoffs:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/task-handoffs/Ef8f2Vmq\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/task-handoffs/{id}', {\n params: { path: { id: 'Ef8f2Vmq' } },\n});" } ] } }, "/time-entries": { "get": { "summary": "List Time Entries", "description": "List timeEntries. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 5 fields. Ordered by `start` unless you pass `sort`. Returns your own entries by default. With viewTimeReports on your role it returns every entry in your team instead; filter `memberId` for one person. This is the endpoint to build a team time report from — `search` stays scoped to your own entries regardless of role.\n\n**Required scope:** `time-entries:read`", "operationId": "listTimeEntries", "tags": [ "timeEntry" ], "x-required-scopes": [ "time-entries:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `start`.", "schema": { "type": "string", "enum": [ "start", "createdAt", "-start", "-createdAt" ] }, "example": "start" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member" ] } }, "style": "form", "explode": false, "example": [ "member" ] }, { "name": "manual[eq]", "in": "query", "required": false, "description": "Filter where `manual` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "start[gt]", "in": "query", "required": false, "description": "Filter where `start` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[gte]", "in": "query", "required": false, "description": "Filter where `start` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lt]", "in": "query", "required": false, "description": "Filter where `start` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lte]", "in": "query", "required": false, "description": "Filter where `start` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "memberId[eq]", "in": "query", "required": false, "description": "Filter where `memberId` equals.", "schema": { "type": "string" }, "example": "P3hYIKqK" }, { "name": "memberId[in]", "in": "query", "required": false, "description": "Filter where `memberId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "P3hYIKqK", "P3hYIKqK" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/timeEntryExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "sfmueIsa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" }, { "id": "czeMwGCa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "time-entries:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/time-entries\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/time-entries');" } ] }, "post": { "summary": "Create Time Entry", "description": "Create a Time Entry. Server-assigned fields are ignored if sent.\n\n**Required scope:** `time-entries:write`", "operationId": "createTimeEntry", "tags": [ "timeEntry" ], "x-required-scopes": [ "time-entries:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member" ] } }, "style": "form", "explode": false, "example": [ "member" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/timeEntryCreate" }, "examples": { "default": { "value": { "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "projectId": "iV6vIU8N", "taskId": "KfS0ha8P" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/timeEntryExpanded" }, "examples": { "default": { "value": { "id": "sfmueIsa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "time-entries:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/time-entries\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"description\":\"A concise description.\",\"start\":\"2026-06-01T12:00:00.000Z\",\"end\":\"2026-06-14T12:00:00.000Z\",\"projectId\":\"iV6vIU8N\",\"taskId\":\"KfS0ha8P\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/time-entries', {\n body: {\n \"description\": \"A concise description.\",\n \"start\": \"2026-06-01T12:00:00.000Z\",\n \"end\": \"2026-06-14T12:00:00.000Z\",\n \"projectId\": \"iV6vIU8N\",\n \"taskId\": \"KfS0ha8P\"\n },\n});" } ] } }, "/time-entries/{id}": { "get": { "summary": "Get Time Entry", "description": "Retrieve a single Time Entry by id. By default only your own entries are reachable here. With viewTimeReports on your role, so is any entry in your team — get widens exactly as list does, so a row you can see in list is a row you can fetch by id. Without that permission another member's entry is 404, not 403.\n\n**Required scope:** `time-entries:read`", "operationId": "getTimeEntry", "tags": [ "timeEntry" ], "x-required-scopes": [ "time-entries:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Time Entry.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "sfmueIsa" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member" ] } }, "style": "form", "explode": false, "example": [ "member" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/timeEntryExpanded" }, "examples": { "default": { "value": { "id": "sfmueIsa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "time-entries:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/time-entries/sfmueIsa\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/time-entries/{id}', {\n params: { path: { id: 'sfmueIsa' } },\n});" } ] }, "patch": { "summary": "Update Time Entry", "description": "Partially update a Time Entry. Only the fields you send are changed.\n\n**Required scope:** `time-entries:write`", "operationId": "updateTimeEntry", "tags": [ "timeEntry" ], "x-required-scopes": [ "time-entries:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Time Entry.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "sfmueIsa" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member" ] } }, "style": "form", "explode": false, "example": [ "member" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/timeEntryUpdate" }, "examples": { "default": { "value": { "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/timeEntryExpanded" }, "examples": { "default": { "value": { "id": "sfmueIsa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "time-entries:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/time-entries/sfmueIsa\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"description\":\"A concise description.\",\"start\":\"2026-06-01T12:00:00.000Z\",\"end\":\"2026-06-14T12:00:00.000Z\",\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/time-entries/{id}', {\n params: { path: { id: 'sfmueIsa' } },\n body: {\n \"description\": \"A concise description.\",\n \"start\": \"2026-06-01T12:00:00.000Z\",\n \"end\": \"2026-06-14T12:00:00.000Z\",\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Time Entry", "description": "Permanently delete this Time Entry. This cannot be undone.\n\n**Required scope:** `time-entries:delete`", "operationId": "deleteTimeEntry", "tags": [ "timeEntry" ], "x-required-scopes": [ "time-entries:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Time Entry.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "sfmueIsa" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "time-entries:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/time-entries/sfmueIsa\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/time-entries/{id}', {\n params: { path: { id: 'sfmueIsa' } },\n});" } ] } }, "/time-entries/search": { "get": { "summary": "Search Time Entries", "description": "Full-text ranked search across timeEntries. Ranked by relevance; pages are capped at 200 results. Filterable by 5 fields. Always scoped to your own entries, whatever your role — unlike list and get, a reporting permission does NOT widen it. Do not build a team report from this endpoint; it will silently under-report.\n\n**Required scope:** `time-entries:read`", "operationId": "searchTimeEntries", "tags": [ "timeEntry" ], "x-required-scopes": [ "time-entries:read" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.", "schema": { "type": "string", "minLength": 3, "maxLength": 200 }, "example": "design" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "member" ] } }, "style": "form", "explode": false, "example": [ "member" ] }, { "name": "manual[eq]", "in": "query", "required": false, "description": "Filter where `manual` equals.", "schema": { "type": "boolean" }, "example": false }, { "name": "start[gt]", "in": "query", "required": false, "description": "Filter where `start` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[gte]", "in": "query", "required": false, "description": "Filter where `start` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lt]", "in": "query", "required": false, "description": "Filter where `start` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "start[lte]", "in": "query", "required": false, "description": "Filter where `start` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-01T12:00:00.000Z" }, { "name": "projectId[eq]", "in": "query", "required": false, "description": "Filter where `projectId` equals.", "schema": { "type": "string" }, "example": "iV6vIU8N" }, { "name": "projectId[in]", "in": "query", "required": false, "description": "Filter where `projectId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "iV6vIU8N", "iV6vIU8N" ] }, { "name": "taskId[eq]", "in": "query", "required": false, "description": "Filter where `taskId` equals.", "schema": { "type": "string" }, "example": "KfS0ha8P" }, { "name": "taskId[in]", "in": "query", "required": false, "description": "Filter where `taskId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "KfS0ha8P", "KfS0ha8P" ] }, { "name": "memberId[eq]", "in": "query", "required": false, "description": "Filter where `memberId` equals.", "schema": { "type": "string" }, "example": "P3hYIKqK" }, { "name": "memberId[in]", "in": "query", "required": false, "description": "Filter where `memberId` is one of (comma-separated list).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "P3hYIKqK", "P3hYIKqK" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/timeEntryExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "sfmueIsa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" }, { "id": "czeMwGCa", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "description": "A concise description.", "start": "2026-06-01T12:00:00.000Z", "end": "2026-06-14T12:00:00.000Z", "manual": false, "projectId": "iV6vIU8N", "memberId": "P3hYIKqK", "taskId": "KfS0ha8P" } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "time-entries:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/time-entries/search?q=design\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/time-entries/search', {\n params: { query: { q: 'design' } },\n});" } ] } }, "/webhooks": { "get": { "summary": "List Webhooks", "description": "List webhooks. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by `-createdAt` unless you pass `sort`.\n\n**Required scope:** `webhooks:read`", "operationId": "listWebhooks", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:read" ], "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "Field to sort by. Prefix with `-` for descending (`-createdAt`); a `createdAt:desc` / `createdAt:asc` suffix works too, but never both markers at once. Default: `-createdAt`.", "schema": { "type": "string", "enum": [ "name", "createdAt", "-name", "-createdAt" ] }, "example": "-createdAt" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor for the next page (the envelope `nextCursor`)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Items per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow `nextCursor` instead of assuming one page held everything." }, { "name": "includeTotal", "in": "query", "schema": { "type": "boolean" }, "description": "When true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination." }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "purgeAt[null]", "in": "query", "required": false, "description": "Filter where `purgeAt` is null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[notNull]", "in": "query", "required": false, "description": "Filter where `purgeAt` is not null (pass `true`).", "schema": { "type": "boolean" }, "example": true }, { "name": "purgeAt[gt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[gte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lt]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "purgeAt[lte]", "in": "query", "required": false, "description": "Filter where `purgeAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-06-30T12:00:00.000Z" }, { "name": "name[eq]", "in": "query", "required": false, "description": "Filter where `name` equals.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[contains]", "in": "query", "required": false, "description": "Filter where `name` contains.", "schema": { "type": "string" }, "example": "Example" }, { "name": "name[startsWith]", "in": "query", "required": false, "description": "Filter where `name` starts with.", "schema": { "type": "string" }, "example": "Example" }, { "name": "active[eq]", "in": "query", "required": false, "description": "Filter where `active` equals.", "schema": { "type": "boolean" }, "example": true }, { "name": "createdAt[gt]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[gte]", "in": "query", "required": false, "description": "Filter where `createdAt` is greater than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lt]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" }, { "name": "createdAt[lte]", "in": "query", "required": false, "description": "Filter where `createdAt` is less than or equal to.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-05-31T12:00:00.000Z" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/webhookExpanded" } } } } ] }, "examples": { "default": { "value": { "data": [ { "id": "GZiSa6Jk", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "ej4HwmyI", "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "createdById": "rBIGEQCa", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 0 }, { "id": "apYGGe87", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "ej4HwmyI", "name": "Second example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "createdById": "rBIGEQCa", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 0 } ], "total": 5, "limit": 2, "hasMore": true, "nextCursor": "b2NjdXJyZWRBdD0yMDI2LTA1LTMxVDEyOjAwOjAwWg" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/webhooks\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/webhooks');" } ] }, "post": { "summary": "Create Webhook", "description": "Create a Webhook. Server-assigned fields are ignored if sent.\n\n**Required scope:** `webhooks:write`", "operationId": "createWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookCreate" }, "examples": { "default": { "value": { "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookCreated" }, "examples": { "default": { "value": { "id": "GZiSa6Jk", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "ej4HwmyI", "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "createdById": "rBIGEQCa", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 0, "secret": "Example secret" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/webhooks\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"url\":\"https://example.com/resource\",\"events\":[\"task.created\",\"task.updated\",\"project.*\"],\"apiVersion\":\"latest\",\"active\":true}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/webhooks', {\n body: {\n \"name\": \"Example\",\n \"url\": \"https://example.com/resource\",\n \"events\": [\n \"task.created\",\n \"task.updated\",\n \"project.*\"\n ],\n \"apiVersion\": \"latest\",\n \"active\": true\n },\n});" } ] } }, "/webhooks/{id}": { "get": { "summary": "Get Webhook", "description": "Retrieve a single Webhook by id.\n\n**Required scope:** `webhooks:read`", "operationId": "getWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookExpanded" }, "examples": { "default": { "value": { "id": "GZiSa6Jk", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "ej4HwmyI", "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "createdById": "rBIGEQCa", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/webhooks/{id}', {\n params: { path: { id: 'GZiSa6Jk' } },\n});" } ] }, "patch": { "summary": "Update Webhook", "description": "Partially update a Webhook. Only the fields you send are changed.\n\n**Required scope:** `webhooks:write`", "operationId": "updateWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "expand", "in": "query", "required": false, "description": "Comma-separated relations to inline (see **Expanding objects** above). Valid values are listed in the enum.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "createdByActor", "updatedByActor" ] } }, "style": "form", "explode": false, "example": [ "createdByActor", "updatedByActor" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookUpdate" }, "examples": { "default": { "value": { "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "expectedUpdatedAt": "2026-05-31T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookExpanded" }, "examples": { "default": { "value": { "id": "GZiSa6Jk", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "ej4HwmyI", "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "createdById": "rBIGEQCa", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X PATCH \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Example\",\"url\":\"https://example.com/resource\",\"events\":[\"task.created\",\"task.updated\",\"project.*\"],\"apiVersion\":\"latest\",\"active\":true,\"expectedUpdatedAt\":\"2026-05-31T12:00:00.000Z\"}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.PATCH('/webhooks/{id}', {\n params: { path: { id: 'GZiSa6Jk' } },\n body: {\n \"name\": \"Example\",\n \"url\": \"https://example.com/resource\",\n \"events\": [\n \"task.created\",\n \"task.updated\",\n \"project.*\"\n ],\n \"apiVersion\": \"latest\",\n \"active\": true,\n \"expectedUpdatedAt\": \"2026-05-31T12:00:00.000Z\"\n },\n});" } ] }, "delete": { "summary": "Delete Webhook", "description": "Move this Webhook to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.\n\n**Required scope:** `webhooks:delete`", "operationId": "deleteWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "204": { "description": "No Content", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X DELETE \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.DELETE('/webhooks/{id}', {\n params: { path: { id: 'GZiSa6Jk' } },\n});" } ] } }, "/webhooks/{id}/test": { "post": { "summary": "Test (Webhook)", "description": "Send a synthetic test event to this webhook's registered URL and report whether the endpoint accepted it. Use it to verify connectivity and signature verification before relying on live events.\n\n**Required scope:** `webhooks:write`", "operationId": "testWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotentReplay": { "type": "boolean", "description": "True when this response was replayed from a previous call with the same Idempotency-Key (no new delivery was attempted)." }, "delivered": { "type": "boolean", "description": "True when the endpoint answered with a 2xx status." }, "statusCode": { "type": "integer", "description": "HTTP status returned by the endpoint. Absent when no response was received (DNS failure, refused connection, timeout)." }, "error": { "type": "string", "description": "Short reason the test delivery failed. Absent when delivered is true." } }, "required": [ "idempotentReplay", "delivered" ], "additionalProperties": false }, "examples": { "default": { "value": { "idempotentReplay": false, "delivered": false, "statusCode": 100, "error": "Example error" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "default": { "value": {} } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk/test\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/webhooks/{id}/test', {\n params: { path: { id: 'GZiSa6Jk' } },\n body: {},\n});" } ] } }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotate secret (Webhook)", "description": "Mint a new HMAC signing secret for this webhook and return it. The new secret is shown exactly once in this response — the previous secret stops verifying immediately.\n\n**Required scope:** `webhooks:write`", "operationId": "rotateSecretWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdByActorId": { "type": [ "string", "null" ] }, "updatedByActorId": { "type": [ "string", "null" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time" }, "deletedById": { "type": [ "string", "null" ] }, "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "apiVersion": { "type": "string", "enum": [ "latest", "2026-03-20" ] }, "active": { "type": "boolean" }, "createdById": { "type": [ "string", "null" ], "minLength": 1 }, "lastDeliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "failCount": { "type": "integer" }, "secret": { "type": "string", "minLength": 1, "description": "The signing secret for this webhook, in plaintext. **Returned exactly once** — here, and again from `POST /webhooks/{id}/rotate-secret` — and never readable afterwards, so store it before you do anything else. Use it to verify the `X-Webhook-Signature` header on every delivery. If you lose it, rotate: `POST /webhooks/{id}/rotate-secret` mints a new one and invalidates the old. NOTE: replaying this exact request with the same `Idempotency-Key` returns the body WITHOUT `secret` — once means once." } }, "required": [ "id", "createdAt", "name", "url", "events", "apiVersion", "active", "failCount", "secret" ], "additionalProperties": false }, "examples": { "default": { "value": { "id": "XXKmAKg6", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "dv63lGmK", "name": "Example", "url": "https://example.com/resource", "events": [ "Example events" ], "apiVersion": "latest", "active": false, "createdById": "EheuyMIk", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 100, "secret": "Example secret" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "default": { "value": {} } } } } }, "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk/rotate-secret\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/webhooks/{id}/rotate-secret', {\n params: { path: { id: 'GZiSa6Jk' } },\n body: {},\n});" } ] } }, "/webhooks/{id}/deliveries": { "get": { "summary": "Deliveries (Webhook)", "description": "List recent delivery attempts for this webhook, newest first — what was sent, whether the endpoint accepted it, and why it failed if it did not. Attempts are kept for 30 days.\n\n**Required scope:** `webhooks:read`", "operationId": "listWebhookDeliveries", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "limit", "in": "query", "required": false, "description": "How many delivery attempts to return, newest first. Between 1 and 100; defaults to 25.", "schema": { "type": "integer" }, "example": 100 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier for this delivery attempt." }, "webhookId": { "type": "string", "description": "The webhook this attempt was made for." }, "eventType": { "type": "string", "description": "The event that was sent, for example `task.created`. Matches the `X-Webhook-Event` header of the request." }, "status": { "type": "string", "enum": [ "delivered", "failed" ], "description": "`delivered` when the endpoint answered with a 2xx status, `failed` otherwise — including when it never answered at all." }, "responseStatus": { "type": [ "integer", "null" ], "description": "HTTP status the endpoint returned. Null when no response was received (name resolution failure, refused connection, timeout)." }, "durationMs": { "type": [ "integer", "null" ], "description": "How long the attempt took, in milliseconds." }, "error": { "type": [ "string", "null" ], "description": "Short reason the attempt failed, for example `HTTP 500` or `Request timed out`. Null when the attempt succeeded. Cut to the first 1024 bytes." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the attempt was recorded." } }, "required": [ "id", "webhookId", "eventType", "status", "responseStatus", "durationMs", "error", "createdAt" ], "additionalProperties": false }, "description": "The page of delivery attempts, newest first." }, "limit": { "type": "integer", "description": "The page size that was applied." }, "hasMore": { "type": "boolean", "description": "True when older attempts exist beyond this page. Ask for a larger page to see more." } }, "required": [ "data", "limit", "hasMore" ], "additionalProperties": false }, "examples": { "default": { "value": { "data": [ { "id": "XXKmAKg6", "webhookId": "GZiSa6Jk", "eventType": "Example event type", "status": "delivered", "responseStatus": 100, "durationMs": 100, "error": "Example error", "createdAt": "2026-05-31T12:00:00.000Z" } ], "limit": 100, "hasMore": false } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:read" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk/deliveries\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\nconst { data } = await nifty.GET('/webhooks/{id}/deliveries', {\n params: { path: { id: 'GZiSa6Jk' } },\n});" } ] } }, "/webhooks/{id}/restore": { "post": { "summary": "Restore Webhook", "description": "Restore a Webhook that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.\n\n**Required scope:** `webhooks:delete`", "operationId": "restoreWebhook", "tags": [ "webhook" ], "x-required-scopes": [ "webhooks:delete" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the Webhook.", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9A-Za-z_!]+$" }, "example": "GZiSa6Jk" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 250 }, "description": "Optional replay key (see **Idempotent requests** above).", "example": "3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "examples": { "default": { "value": { "id": "GZiSa6Jk", "createdAt": "2026-05-31T12:00:00.000Z", "updatedAt": "2026-05-31T14:00:00.000Z", "createdByActorId": "49f861f7-4af8-44bf-844f-45f85babe504", "updatedByActorId": "3306ed14-3606-4350-8300-2f06e6c80dce", "createdByActorType": "human", "updatedByActorType": "human", "purgeAt": "2026-06-30T12:00:00.000Z", "deletedById": "ej4HwmyI", "name": "Example", "url": "https://example.com/resource", "events": [ "task.created", "task.updated", "project.*" ], "apiVersion": "latest", "active": true, "createdById": "rBIGEQCa", "lastDeliveredAt": "2026-06-06T03:00:00.000Z", "failCount": 0 } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/UpstreamUnavailable" } }, "security": [ { "bearerAuth": [] }, { "oauth2": [ "webhooks:delete" ] } ], "x-codeSamples": [ { "lang": "shell", "label": "curl", "source": "curl -X POST \"https://openapi.niftypm.com/api/v3/webhooks/GZiSa6Jk/restore\" \\\n -H \"Authorization: Bearer $NIFTY_TOKEN\" \\\n -H \"Idempotency-Key: 3f0b1c8a-9f0e-4a2f-8f5e-2b7c9d1e4a60\"" }, { "lang": "typescript", "label": "@niftypm/api", "source": "import { createNiftyClient } from '@niftypm/api';\n\nconst nifty = createNiftyClient({ token: process.env.NIFTY_TOKEN! });\n\n// The client sends an Idempotency-Key of its own on every POST.\nconst { data } = await nifty.POST('/webhooks/{id}/restore', {\n params: { path: { id: 'GZiSa6Jk' } },\n});" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "nft_user_* (personal access token) or nft_oauth_* (OAuth 2.1 access token)" }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorization code flow with PKCE, for an app acting on behalf of a Nifty user. The access token is sent as `Authorization: Bearer nft_oauth_…`, exactly like a personal access token.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.niftypm.com/oauth/authorize", "tokenUrl": "https://api.niftypm.com/oauth/token", "refreshUrl": "https://api.niftypm.com/oauth/token", "scopes": { "read": "Read access to every resource the grant covers.", "write": "Read, create and update every resource the grant covers. Does NOT include deleting — ask for `admin` or the explicit `:delete` scope for that.", "admin": "Full access, including deletes.", "actors:read": "Read actors", "annotations:delete": "Delete annotations", "annotations:read": "Read annotations", "annotations:write": "Create and update annotations", "chats:delete": "Delete chats", "chats:read": "Read chats", "chats:write": "Create and update chats", "check-in-requests:delete": "Delete check in requests", "check-in-requests:link": "Link and unlink check in requests relations (assignees, labels, members) without creating, updating or deleting the check in requests themselves", "check-in-requests:read": "Read check in requests", "check-in-requests:write": "Create and update check in requests", "check-ins:delete": "Delete check ins", "check-ins:link": "Link and unlink check ins relations (assignees, labels, members) without creating, updating or deleting the check ins themselves", "check-ins:read": "Read check ins", "check-ins:write": "Create and update check ins", "checklist-items:delete": "Delete checklist items", "checklist-items:read": "Read checklist items", "checklist-items:write": "Create and update checklist items", "checklists:delete": "Delete checklists", "checklists:read": "Read checklists", "checklists:write": "Create and update checklists", "custom-fields:read": "Read custom fields", "documents:delete": "Delete documents", "documents:link": "Link and unlink documents relations (assignees, labels, members) without creating, updating or deleting the documents themselves", "documents:read": "Read documents", "documents:write": "Create and update documents", "favorite-folders:delete": "Delete favorite folders", "favorite-folders:read": "Read favorite folders", "favorite-folders:write": "Create and update favorite folders", "favorites:delete": "Delete favorites", "favorites:read": "Read favorites", "favorites:write": "Create and update favorites", "files:delete": "Delete files", "files:link": "Link and unlink files relations (assignees, labels, members) without creating, updating or deleting the files themselves", "files:read": "Read files", "files:write": "Create and update files", "forms:delete": "Delete forms", "forms:read": "Read forms", "goal-groups:delete": "Delete goal groups", "goal-groups:read": "Read goal groups", "goal-groups:write": "Create and update goal groups", "goals:delete": "Delete goals", "goals:read": "Read goals", "goals:write": "Create and update goals", "labels:delete": "Delete labels", "labels:read": "Read labels", "labels:write": "Create and update labels", "lists:delete": "Delete lists", "lists:link": "Link and unlink lists relations (assignees, labels, members) without creating, updating or deleting the lists themselves", "lists:read": "Read lists", "lists:write": "Create and update lists", "members:delete": "Delete members", "members:read": "Read members", "members:write": "Create and update members", "messages:delete": "Delete messages", "messages:read": "Read messages", "messages:write": "Create and update messages", "portfolios:delete": "Delete portfolios", "portfolios:link": "Link and unlink portfolios relations (assignees, labels, members) without creating, updating or deleting the portfolios themselves", "portfolios:read": "Read portfolios", "portfolios:write": "Create and update portfolios", "presence-statuses:delete": "Delete presence statuses", "presence-statuses:read": "Read presence statuses", "presence-statuses:write": "Create and update presence statuses", "project-activities:read": "Read project activities", "project-dashboards:delete": "Delete project dashboards", "project-dashboards:read": "Read project dashboards", "project-dashboards:write": "Create and update project dashboards", "project-folders:delete": "Delete project folders", "project-folders:read": "Read project folders", "project-folders:write": "Create and update project folders", "projects:delete": "Delete projects", "projects:read": "Read projects", "projects:write": "Create and update projects", "recurring-rules:delete": "Delete recurring rules", "recurring-rules:read": "Read recurring rules", "recurring-rules:write": "Create and update recurring rules", "reminders:delete": "Delete reminders", "reminders:read": "Read reminders", "reminders:write": "Create and update reminders", "report-charts:delete": "Delete report charts", "report-charts:link": "Link and unlink report charts relations (assignees, labels, members) without creating, updating or deleting the report charts themselves", "report-charts:read": "Read report charts", "report-charts:write": "Create and update report charts", "roles:delete": "Delete roles", "roles:read": "Read roles", "roles:write": "Create and update roles", "statuses:delete": "Delete statuses", "statuses:link": "Link and unlink statuses relations (assignees, labels, members) without creating, updating or deleting the statuses themselves", "statuses:read": "Read statuses", "statuses:write": "Create and update statuses", "task-handoffs:delete": "Delete task handoffs", "task-handoffs:read": "Read task handoffs", "task-handoffs:write": "Create and update task handoffs", "tasks:delete": "Delete tasks", "tasks:link": "Link and unlink tasks relations (assignees, labels, members) without creating, updating or deleting the tasks themselves", "tasks:read": "Read tasks", "tasks:write": "Create and update tasks", "time-entries:delete": "Delete time entries", "time-entries:read": "Read time entries", "time-entries:write": "Create and update time entries", "webhooks:delete": "Delete webhooks", "webhooks:read": "Read webhooks", "webhooks:write": "Create and update webhooks" } } } } }, "schemas": { "Error": { "type": "object", "description": "RFC 7807 Problem Details error, with Nifty extensions (`code`, `requestId`, `docsUrl`).", "properties": { "type": { "type": "string", "example": "resource_not_found" }, "title": { "type": "string", "example": "Resource not found" }, "status": { "type": "integer", "example": 404 }, "detail": { "type": "string", "example": "task 'KfS0ha8P' not found or inaccessible" }, "instance": { "type": "string", "example": "/tasks/KfS0ha8P" }, "code": { "type": "string", "enum": [ "validation_failed", "cursor_invalid", "cursor_sort_mismatch", "pagination_param_unknown", "sort_field_invalid", "resource_unknown", "resource_misconfigured", "search_query_missing", "search_query_too_short", "search_query_too_long", "search_query_invalid", "search_timed_out", "identity_rejected", "empty_update", "project_not_specified", "accessible_project_ids_exceeded", "milestone_dependency_wrong_project", "milestone_hiddenfor_roles_not_in_team", "favorite_folder_invalid", "expand_too_deep", "expand_cycle_detected", "expand_unknown_relation", "expand_budget_exceeded", "invalid_field_selector", "invalid_query_param", "move_target_milestone_mismatch", "move_target_taskgroup_mismatch", "move_target_no_default_milestone", "move_target_no_default_taskgroup", "task_no_default_status", "move_subtask_must_move_with_parent", "task_subtask_chain_too_deep", "task_dependency_incomplete", "bulk_too_large", "batch_empty", "batch_too_large", "m2m_relation_unknown", "m2m_target_not_found", "m2m_not_supported", "unauthorized", "invalid_token", "token_expired", "token_owner_inactive", "pat_cap_reached", "cannot_broaden_scope", "cannot_shorten_expiry", "cannot_create_empty_token", "permission_denied", "project_access_denied", "default_label_locked", "default_role_locked", "permission_exceeds_caller_grant", "resource_not_found", "conflict", "duplicate_label", "duplicate_role", "role_in_use", "regular_role_missing", "stale_write", "idempotency_key_reuse", "idempotency_in_progress", "name_contains_url", "name_contains_email", "name_contains_html", "name_contains_script", "team_storage_quota_exceeded", "rate_limited", "free_plan_write_cap_exceeded", "quota_exceeded", "not_implemented", "create_not_durable", "internal_error", "actor_resolution_failed", "response_schema_violation", "route_not_found" ], "example": "resource_not_found" }, "requestId": { "type": "string", "format": "uuid", "example": "486de74d-2334-46ee-a583-8b5e4680f7c4" }, "docsUrl": { "type": "string", "format": "uri", "example": "https://developers.niftypm.com/docs/errors#resource_not_found" } }, "required": [ "type", "title", "status", "detail", "code" ] }, "ValidationError": { "description": "A 400 validation failure: the Problem Details envelope plus a per-field `errors` array.", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "errors": { "type": "array", "description": "One entry per field that failed validation.", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "name" }, "code": { "type": "string", "example": "required" }, "message": { "type": "string", "example": "label requires at least one of: name, color" } } } } } } ] }, "PaginatedEnvelope": { "type": "object", "description": "Cursor-paginated collection envelope.", "properties": { "data": { "type": "array", "items": {}, "description": "The page of results." }, "total": { "type": "integer", "description": "Total rows matching the query (across pages).", "example": 42 }, "limit": { "type": "integer", "example": 50 }, "hasMore": { "type": "boolean", "example": false }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null on the last page." } }, "required": [ "data" ] }, "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Actor id. A UUID — unlike the short ids used elsewhere in this API. This is the value returned as createdByActorId, updatedByActorId and actorId on other resources.", "readOnly": true, "example": "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013", "examples": [ "3f1a9c8e-5b2d-4e77-9a10-6c4de2f8b013" ] }, "type": { "type": "string", "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "What kind of writer this is: \"human\" a person, \"agent\" an autonomous integration, \"automation\" a workspace rule, \"recurringTask\" a repeating task rule, \"cron\" a scheduled maintenance job, \"outboxRetry\" a retried delivery, \"systemDefault\" an unattributed server write. Branch on this to tell a person's edit from an automated one.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "displayName": { "type": [ "string", "null" ], "description": "Name to show for this actor: the person's name, the agent's name, or a label for a server process. A cached convenience copy that can briefly lag a rename, so treat the member or agent record as authoritative when you have it. \"Deleted member\" once the underlying person has been erased.", "readOnly": true, "example": "Example", "examples": [ "Example" ] }, "memberId": { "type": [ "string", "null" ], "minLength": 1, "description": "The person behind this actor, when type is \"human\" — look it up on /members for name, avatar, role and status. Null for every other type, and null once the person has been erased.", "readOnly": true, "example": "P3hYIKqK", "examples": [ "P3hYIKqK" ] }, "agentId": { "type": [ "string", "null" ], "minLength": 1, "description": "The agent behind this actor, when type is \"agent\". Null for every other type, and null once the agent has been deleted.", "readOnly": true, "example": "8EO45hmm", "examples": [ "8EO45hmm" ] }, "tombstonedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the person or agent behind this actor was permanently erased. The actor survives so past attribution stays intact, but it no longer identifies anyone: memberId and agentId are cleared and displayName becomes a placeholder. Null for every live actor.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] } }, "required": [ "id", "type" ], "additionalProperties": false }, "annotation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "863BiyIc", "examples": [ "863BiyIc" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "type": { "type": "string", "enum": [ "image", "video" ], "description": "Annotation kind: image or video.", "example": "image", "examples": [ "image" ] }, "geometry": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "POINT" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y" ], "additionalProperties": true }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "RECTANGLE" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y", "width", "height" ], "additionalProperties": true }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OVAL" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y", "width", "height" ], "additionalProperties": true } ] }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Where the annotation sits on an image: the shape kind (`POINT`, `RECTANGLE` or `OVAL`) plus `x` / `y` / `width` / `height`. All four are PERCENTAGES of the file's own dimensions (0–100), not pixels, so an annotation keeps its place at any display size. A `POINT` needs only `x` and `y`. Empty for a bare anchor.", "example": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "examples": [ { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 } ] }, "videoTimeSeconds": { "type": [ "number", "null" ], "description": "Playback position in seconds for a video annotation. Null for image annotations.", "example": 42.5, "examples": [ 42.5 ] }, "fileId": { "type": "string", "minLength": 1, "description": "The file this annotation is drawn on. Required and immutable.", "example": "xvM2toUM", "examples": [ "xvM2toUM" ] }, "taskId": { "type": [ "string", "null" ], "description": "The task that holds this annotation's comment thread. Created automatically when someone comments on the annotation in the Nifty app; null until then.", "readOnly": true, "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": [ "string", "null" ] }, "authorId": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id" ], "additionalProperties": true }, "description": "Messages threaded under this annotation — what the app calls its comments. Populated only when you ask for it with `?expand=messages`; also reachable as `GET /messages?annotationId=...`.", "example": [], "examples": [ [] ] } }, "required": [ "id", "createdAt", "type", "fileId" ], "additionalProperties": true }, "annotationExpanded": { "description": "A Annotation with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/annotation" }, { "type": "object", "properties": { "file": { "allOf": [ { "$ref": "#/components/schemas/file" } ], "description": "The related File, present only when you pass `?expand=file`.", "x-example-omit": true }, "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "annotationCreate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "description": "Annotation kind: image or video.", "example": "image", "examples": [ "image" ], "x-createOnly": true }, "geometry": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "POINT" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "RECTANGLE" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y", "width", "height" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OVAL" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y", "width", "height" ], "additionalProperties": false } ], "description": "Where the annotation sits on an image: the shape kind (`POINT`, `RECTANGLE` or `OVAL`) plus `x` / `y` / `width` / `height`. All four are PERCENTAGES of the file's own dimensions (0–100), not pixels, so an annotation keeps its place at any display size. A `POINT` needs only `x` and `y`. Empty for a bare anchor.", "example": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "examples": [ { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 } ] }, "videoTimeSeconds": { "type": [ "number", "null" ], "description": "Playback position in seconds for a video annotation. Null for image annotations.", "example": 42.5, "examples": [ 42.5 ] }, "fileId": { "type": "string", "minLength": 1, "description": "The file this annotation is drawn on. Required and immutable.", "example": "xvM2toUM", "examples": [ "xvM2toUM" ], "x-createOnly": true } }, "required": [ "type", "fileId" ], "additionalProperties": false }, "annotationUpdate": { "type": "object", "properties": { "geometry": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "POINT" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "RECTANGLE" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y", "width", "height" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OVAL" ] }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "type", "x", "y", "width", "height" ], "additionalProperties": false } ], "description": "Where the annotation sits on an image: the shape kind (`POINT`, `RECTANGLE` or `OVAL`) plus `x` / `y` / `width` / `height`. All four are PERCENTAGES of the file's own dimensions (0–100), not pixels, so an annotation keeps its place at any display size. A `POINT` needs only `x` and `y`. Empty for a bare anchor.", "example": { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 }, "examples": [ { "type": "RECTANGLE", "x": 12.5, "y": 40, "width": 25, "height": 10 } ] }, "videoTimeSeconds": { "type": [ "number", "null" ], "description": "Playback position in seconds for a video annotation. Null for image annotations.", "example": 42.5, "examples": [ 42.5 ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "chat": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "hTIeouEK", "examples": [ "hTIeouEK" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": [ "string", "null" ], "description": "Chat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional free-text description.", "example": "A concise description.", "examples": [ "A concise description." ] }, "type": { "type": "string", "enum": [ "group", "direct", "project" ], "description": "Chat type: 'group', 'direct' (a 1:1 direct message), or 'project' (a project's general discussion). Create accepts ONLY 'group'.", "example": "group", "examples": [ "group" ] }, "teamId": { "type": [ "string", "null" ], "minLength": 1, "description": "The workspace (team) this chat belongs to. Server-set from the caller identity — never client-writable.", "readOnly": true, "example": "cfC83TeS", "examples": [ "cfC83TeS" ] }, "projectId": { "type": [ "string", "null" ], "description": "Set only on a project's general-discussion chat; null on group and direct chats. Those chats are not returned by list/get today, so in practice this is always null.", "readOnly": true, "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "pinnedMessageId": { "type": [ "string", "null" ], "description": "The message currently pinned in this chat, if any. Read-only.", "readOnly": true, "example": "ytAkOyYK", "examples": [ "ytAkOyYK" ] }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the latest message (server-bumped by the message-create afterCommit hook). NULL until the first message. List default-sorts on it.", "readOnly": true, "example": "2026-06-02T18:00:00.000Z", "examples": [ "2026-06-02T18:00:00.000Z" ] }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "memberId": { "type": [ "string", "null" ] }, "isOwner": { "type": [ "boolean", "null" ] }, "isMuted": { "type": [ "boolean", "null" ] }, "joined": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id" ], "additionalProperties": true }, "description": "Who is in this chat. Each entry carries the member id plus whether they own the chat, whether they muted it, and when they joined. Populated only when you ask for it with `?expand=members`.", "example": [], "examples": [ [] ] } }, "required": [ "id", "createdAt", "type" ], "additionalProperties": true }, "chatExpanded": { "description": "A Chat with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/chat" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "chatCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Chat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional free-text description.", "example": "A concise description.", "examples": [ "A concise description." ] }, "type": { "type": "string", "enum": [ "group" ], "description": "Chat type. Create accepts ONLY a group chat: pass 'group' (the same value reads emit). Direct and project chats are readable but are not created here — post a message with `recipientMemberId` for a direct message; a project's discussion is provisioned with its project.", "example": "group", "examples": [ "group" ], "x-createOnly": true }, "memberIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members to add to the chat, by id — you are always included as its owner. Members are set here, when the chat is created, and cannot be changed afterwards, so send the full roster now. Write-only; read the resulting membership back with `?expand=members`.", "example": [ "8oqm2XKk" ], "examples": [ [ "8oqm2XKk" ] ], "x-createOnly": true } }, "required": [ "name" ], "additionalProperties": false }, "chatUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Chat display name. Required for group chats (the only v3-creatable kind); NULL on direct chats and the team self-chat.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional free-text description.", "example": "A concise description.", "examples": [ "A concise description." ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "checkIn": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "8cQSsSK8", "examples": [ "8cQSsSK8" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "description": "Display name for the check-in. Capped at 100 characters.", "example": "Example", "examples": [ "Example" ] }, "notifyTypes": { "type": "array", "items": { "type": "string", "enum": [ "email", "message", "notification" ] }, "description": "How assignees are reminded: `email`, `message` (an in-app message) or `notification` (a push notification). Every channel you list fires. Usually non-empty, but older records can come back with an empty list — read it, and if you are echoing a record back on an update, drop the key rather than sending the empty array (writes require at least one channel and will reject it).", "example": [ "email" ], "examples": [ [ "email" ] ] }, "requestType": { "type": "string", "enum": [ "schedule", "manual" ], "description": "What triggers this check-in. `schedule` runs it on a recurrence and REQUIRES `recurringRuleId`; `manual` runs it on demand and must omit `recurringRuleId`.", "example": "schedule", "examples": [ "schedule" ] }, "formId": { "type": "string", "minLength": 1, "description": "The form holding this check-in's questions. Set once when the check-in is created.", "example": "Jt0ByAIi", "examples": [ "Jt0ByAIi" ] }, "recurringRuleId": { "type": [ "string", "null" ], "description": "Identifier of the recurrence rule that triggers this check-in, or null when `requestType` is `manual`. Create the rule first with `POST /recurring-rules` and pass its id here, or send an inline `schedule` object on the create body instead and one will be created for you.", "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] } }, "required": [ "id", "createdAt", "name", "notifyTypes", "requestType", "formId" ], "additionalProperties": true }, "checkInExpanded": { "description": "A Check-in with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/checkIn" }, { "type": "object", "properties": { "form": { "allOf": [ { "$ref": "#/components/schemas/form" } ], "description": "The related Form, present only when you pass `?expand=form`.", "x-example-omit": true }, "recurringRule": { "allOf": [ { "$ref": "#/components/schemas/recurringRule" } ], "description": "The related Recurring Rule, present only when you pass `?expand=recurringRule`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=assignees`.", "x-example-omit": true }, "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=subscribers`.", "x-example-omit": true }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/checkInRequest" }, "description": "The linked Check-in request rows, present only when you pass `?expand=requests`.", "x-example-omit": true } } } ] }, "checkInCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the check-in. Capped at 100 characters.", "example": "Example", "examples": [ "Example" ] }, "notifyTypes": { "type": "array", "items": { "type": "string", "enum": [ "email", "message", "notification" ] }, "minItems": 1, "description": "How assignees are reminded: `email`, `message` (an in-app message) or `notification` (a push notification). Every channel you list fires, and at least one is required.", "example": [ "email" ], "examples": [ [ "email" ] ] }, "requestType": { "type": "string", "enum": [ "schedule", "manual" ], "description": "What triggers this check-in. `schedule` runs it on a recurrence and REQUIRES `recurringRuleId`; `manual` runs it on demand and must omit `recurringRuleId`.", "example": "schedule", "examples": [ "schedule" ] }, "formId": { "type": "string", "minLength": 1, "description": "The form holding this check-in's questions. Set once when the check-in is created.", "example": "Jt0ByAIi", "examples": [ "Jt0ByAIi" ], "x-createOnly": true }, "recurringRuleId": { "type": [ "string", "null" ], "description": "Identifier of the recurrence rule that triggers this check-in, or null when `requestType` is `manual`. Create the rule first with `POST /recurring-rules` and pass its id here, or send an inline `schedule` object on the create body instead and one will be created for you.", "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] }, "schedule": { "type": "object", "additionalProperties": {}, "description": "Define the recurrence inline instead of pre-creating a rule: send the same timetable object `recurringRule.schedule` carries and a `recurringRule` is created in the same transaction and linked, so a failure anywhere rolls both back. This is the one-call alternative to `recurringRuleId` and mutually exclusive with it. Accepted on create only — change the schedule of an existing check-in by pointing `recurringRuleId` at another rule.", "example": {}, "examples": [ {} ], "x-createOnly": true }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members who must answer this check-in. Replaces the whole set on update; use `POST /check-ins/{id}/assignees` and `POST /check-ins/{id}/assignees/remove` for a single add or remove.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] }, "subscribers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members notified when someone answers, without being asked themselves. Replaces the whole set on update; use `POST /check-ins/{id}/subscribers` and `POST /check-ins/{id}/subscribers/remove` for a single add or remove.", "example": [ "NlUEieKe" ], "examples": [ [ "NlUEieKe" ] ] } }, "required": [ "name", "notifyTypes", "requestType", "formId" ], "additionalProperties": false }, "checkInUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the check-in. Capped at 100 characters.", "example": "Example", "examples": [ "Example" ] }, "notifyTypes": { "type": "array", "items": { "type": "string", "enum": [ "email", "message", "notification" ] }, "minItems": 1, "description": "How assignees are reminded: `email`, `message` (an in-app message) or `notification` (a push notification). Every channel you list fires, and at least one is required.", "example": [ "email" ], "examples": [ [ "email" ] ] }, "requestType": { "type": "string", "enum": [ "schedule", "manual" ], "description": "What triggers this check-in. `schedule` runs it on a recurrence and REQUIRES `recurringRuleId`; `manual` runs it on demand and must omit `recurringRuleId`.", "example": "schedule", "examples": [ "schedule" ] }, "recurringRuleId": { "type": [ "string", "null" ], "description": "Identifier of the recurrence rule that triggers this check-in, or null when `requestType` is `manual`. Create the rule first with `POST /recurring-rules` and pass its id here, or send an inline `schedule` object on the create body instead and one will be created for you.", "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members who must answer this check-in. Replaces the whole set on update; use `POST /check-ins/{id}/assignees` and `POST /check-ins/{id}/assignees/remove` for a single add or remove.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] }, "subscribers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members notified when someone answers, without being asked themselves. Replaces the whole set on update; use `POST /check-ins/{id}/subscribers` and `POST /check-ins/{id}/subscribers/remove` for a single add or remove.", "example": [ "NlUEieKe" ], "examples": [ [ "NlUEieKe" ] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "checkInRequest": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "fVCU89x0", "examples": [ "fVCU89x0" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "checkInId": { "type": "string", "minLength": 1, "description": "The check-in this request belongs to. Required when creating one, and immutable afterwards — the parent check-in decides both the workspace it lives in and the form that is answered.", "example": "8cQSsSK8", "examples": [ "8cQSsSK8" ] }, "reminderSentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the most recent reminder for this request was sent, or `null` if no reminder has been sent yet. Server-managed (reminders are rate-limited to one every 8 hours) and read-only.", "readOnly": true, "example": "2026-06-08T09:00:00.000Z", "examples": [ "2026-06-08T09:00:00.000Z" ] }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "avatar": { "type": [ "string", "null" ] }, "initials": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "online": { "type": [ "boolean", "null" ] }, "tzIana": { "type": [ "string", "null" ] } }, "required": [ "id" ], "additionalProperties": true }, "description": "Team members asked to respond to this request. Copied from the parent check-in when the request is created; send an `assignees` array on the create body to override that. Add or remove members afterwards with POST/DELETE /check-in-requests/:id/assignees, and use `?expand=assignees` to read them.", "example": [], "examples": [ [] ] }, "respondedBy": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "avatar": { "type": [ "string", "null" ] }, "initials": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "online": { "type": [ "boolean", "null" ] }, "tzIana": { "type": [ "string", "null" ] } }, "required": [ "id" ], "additionalProperties": true }, "description": "Team members who have submitted an answer to this request. Maintained by the submission flow and read-only — a request is complete once this covers every entry in `assignees`. Use `?expand=respondedBy` to read it.", "example": [], "examples": [ [] ] } }, "required": [ "id", "createdAt", "checkInId" ], "additionalProperties": true }, "checkInRequestExpanded": { "description": "A Check-in request with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/checkInRequest" }, { "type": "object", "properties": { "checkIn": { "allOf": [ { "$ref": "#/components/schemas/checkIn" } ], "description": "The related Check-in, present only when you pass `?expand=checkIn`.", "x-example-omit": true } } } ] }, "checkInRequestCreate": { "type": "object", "properties": { "checkInId": { "type": "string", "minLength": 1, "description": "The check-in this request belongs to. Required when creating one, and immutable afterwards — the parent check-in decides both the workspace it lives in and the form that is answered.", "example": "8cQSsSK8", "examples": [ "8cQSsSK8" ], "x-createOnly": true }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members asked to respond to this request. Copied from the parent check-in when the request is created; send an `assignees` array on the create body to override that. Add or remove members afterwards with POST/DELETE /check-in-requests/:id/assignees, and use `?expand=assignees` to read them.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] } }, "required": [ "checkInId" ], "additionalProperties": false }, "checklist": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "NrmgIiU8", "examples": [ "NrmgIiU8" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "description": "Checklist name — a group of steps on the task.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the checklist within its task. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "taskId": { "type": "string", "minLength": 1, "description": "Task this checklist belongs to. Required on create; immutable afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] } }, "required": [ "id", "createdAt", "name", "taskId" ], "additionalProperties": true }, "checklistExpanded": { "description": "A Checklist with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/checklist" }, { "type": "object", "properties": { "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "checklistItems": { "type": "array", "items": { "$ref": "#/components/schemas/checklistItem" }, "description": "The linked Checklist Item rows, present only when you pass `?expand=checklistItems`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "checklistCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Checklist name — a group of steps on the task.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the checklist within its task. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "taskId": { "type": "string", "minLength": 1, "description": "Task this checklist belongs to. Required on create; immutable afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ], "x-createOnly": true } }, "required": [ "name", "taskId" ], "additionalProperties": false }, "checklistUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Checklist name — a group of steps on the task.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the checklist within its task. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "checklistItem": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "iLCQkeWQ", "examples": [ "iLCQkeWQ" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "description": "The item text — a single completable checkbox line (no assignee, dates, or comments).", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the item within its checklist. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "completed": { "type": "boolean", "description": "Whether the item is checked off. Defaults to false.", "example": false, "examples": [ false ] }, "checklistId": { "type": "string", "minLength": 1, "description": "Checklist this item belongs to. Required on create; immutable afterwards.", "example": "NrmgIiU8", "examples": [ "NrmgIiU8" ] } }, "required": [ "id", "createdAt", "name", "completed", "checklistId" ], "additionalProperties": true }, "checklistItemExpanded": { "description": "A Checklist Item with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/checklistItem" }, { "type": "object", "properties": { "checklist": { "allOf": [ { "$ref": "#/components/schemas/checklist" } ], "description": "The related Checklist, present only when you pass `?expand=checklist`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "checklistItemCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The item text — a single completable checkbox line (no assignee, dates, or comments).", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the item within its checklist. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "completed": { "type": "boolean", "description": "Whether the item is checked off. Defaults to false.", "example": false, "examples": [ false ] }, "checklistId": { "type": "string", "minLength": 1, "description": "Checklist this item belongs to. Required on create; immutable afterwards.", "example": "NrmgIiU8", "examples": [ "NrmgIiU8" ], "x-createOnly": true } }, "required": [ "name", "checklistId" ], "additionalProperties": false }, "checklistItemUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The item text — a single completable checkbox line (no assignee, dates, or comments).", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the item within its checklist. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "completed": { "type": "boolean", "description": "Whether the item is checked off. Defaults to false.", "example": false, "examples": [ false ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "customField": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "6GWCcskG", "examples": [ "6GWCcskG" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "name": { "type": "string", "minLength": 1, "description": "Field name, for example \"Priority\" or \"T-shirt size\".", "readOnly": true, "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional help text for this field.", "readOnly": true, "example": "A concise description.", "examples": [ "A concise description." ] }, "type": { "type": "string", "enum": [ "dropdown", "text", "reminder", "number", "url", "phone", "email", "location", "currency", "checkbox", "budget", "calc", "date", "user", "datesdiff" ], "description": "What kind of value this field holds. It decides how you format the string you send: `checkbox` takes `\"true\"` / `\"false\"`, `user` takes a member id, `dropdown` takes one of the field's option values, and the rest take the value written out (a number, a date, a URL).", "readOnly": true, "example": "dropdown", "examples": [ "dropdown" ] }, "associations": { "type": "array", "items": { "type": "string", "enum": [ "project", "list", "task", "member" ] }, "description": "The kinds of thing this field can be attached to.", "readOnly": true, "example": [ "task", "project" ], "examples": [ [ "task", "project" ] ] }, "currency": { "type": [ "string", "null" ], "description": "ISO currency code for a `currency` field. Null for every other type.", "readOnly": true, "example": "USD", "examples": [ "USD" ] }, "inLibrary": { "type": "boolean", "description": "Whether this definition comes from the reusable field library rather than being bound to one workspace. Library definitions are not returned by this API today, so it is always false here.", "readOnly": true, "example": false, "examples": [ false ] }, "teamId": { "type": "string", "minLength": 1, "description": "The workspace (team) this field definition belongs to.", "readOnly": true, "example": "cfC83TeS", "examples": [ "cfC83TeS" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "value": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] } }, "required": [ "id" ], "additionalProperties": true }, "description": "The selectable choices, for a `dropdown` field. Fetch them with `?expand=options` and send one of the returned `value`s when setting the field.", "example": [], "examples": [ [] ] }, "hiddenFor": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": [ "string", "null" ] } }, "required": [ "id" ], "additionalProperties": true }, "description": "Roles this field is hidden from. Read-only here — fetch it with `?expand=hiddenFor`; visibility is managed in the Nifty app.", "example": [], "examples": [ [] ] } }, "required": [ "id", "createdAt", "name", "type", "associations", "inLibrary", "teamId" ], "additionalProperties": true }, "document": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "ELe0nkum", "examples": [ "ELe0nkum" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "Wfw0dIGm", "examples": [ "Wfw0dIGm" ] }, "name": { "type": "string", "description": "Document display name. Required on create; editable.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "1–3 sentence summary of what this document is for (max 2,000 chars; null = none). Surfaced in list results so agents can discover a project's knowledge without fetching bodies. Set it when creating a document; keep it short — it is metadata, not a second body.", "example": "A concise description.", "examples": [ "A concise description." ] }, "archived": { "type": "boolean", "description": "Whether the document is archived. Archived documents stay in the project but are hidden from default views. Independent of deletion — an archived document is not deleted, and a deleted document is not archived.", "example": false, "examples": [ false ] }, "accessType": { "type": "string", "enum": [ "public", "limited", "private" ], "description": "Who can see this document. `public` (the default) — everyone in the project. `limited` — only the document's own member list, which starts out as JUST THE RESOLVED AUTHOR: when an agent or integration creates a limited document, the author it resolves to is the one who can reach it, not the caller. `private` — a legacy state the API cannot set; those documents are readable and filterable but cannot be created here. Choose this when you create the document — it cannot be changed afterwards through the API (change it in the Nifty app instead). A child document always inherits its parent's access type.", "example": "public", "examples": [ "public" ] }, "type": { "type": "string", "enum": [ "nifty", "google", "dropbox", "microsoft" ], "description": "Where the document lives: `nifty` (a native Nifty document — everything the API creates), or `google` / `dropbox` / `microsoft` for a document linked from that provider. Read-only.", "readOnly": true, "example": "nifty", "examples": [ "nifty" ] }, "subtype": { "type": [ "string", "null" ], "enum": [ "document", "spreadsheet", "presentation" ], "description": "What kind of file a linked Google/Microsoft document is: `document`, `spreadsheet` or `presentation`. Null for native Nifty documents. Read-only.", "readOnly": true, "example": "document", "examples": [ "document" ] }, "projectId": { "type": [ "string", "null" ], "description": "The project this document belongs to. Required on create — a document always lives in a project — and immutable afterwards.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "authorId": { "type": [ "string", "null" ], "description": "The team member credited as the document's author — a member id, so resolve it with `?expand=author` or `GET /members/{id}`. When an agent or integration creates a document it resolves to a person (the project owner), and is null only if no person can be resolved. Read-only.", "readOnly": true, "example": "EPmKiCaK", "examples": [ "EPmKiCaK" ] }, "parentDocumentId": { "type": [ "string", "null" ], "description": "The document this one is nested under — a parent in the same project. Set once at creation and immutable thereafter.", "example": "429XYeO6", "examples": [ "429XYeO6" ] }, "folderId": { "type": [ "string", "null" ], "description": "The folder this document sits in — a document folder in the same project. Omit or send null to place it at the project root. The folder path is derived by the server. Set once at creation; moving a document between folders is not part of the update surface yet.", "example": "dBGa8nam", "examples": [ "dBGa8nam" ] }, "locked": { "type": "boolean", "description": "Whether the document is locked against edits.", "example": false, "examples": [ false ] }, "externalId": { "type": [ "string", "null" ], "description": "The provider's own id for a Google/Microsoft-linked document. Null for Nifty-native documents (everything created through this API). Read-only.", "readOnly": true, "example": "kdGCOQ47", "examples": [ "kdGCOQ47" ] }, "externalEmbedUrl": { "type": [ "string", "null" ], "description": "Embed URL for a document linked from another provider. Null for Nifty-native documents (everything created through this API). Read-only.", "readOnly": true, "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] } }, "required": [ "id", "createdAt", "name", "archived", "accessType", "type", "locked" ], "additionalProperties": true }, "documentExpanded": { "description": "A Document with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/document" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "author": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=author`.", "x-example-omit": true }, "parentDocument": { "allOf": [ { "$ref": "#/components/schemas/document" } ], "description": "The related Document, present only when you pass `?expand=parentDocument`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The linked Label rows, present only when you pass `?expand=labels`.", "x-example-omit": true } } } ] }, "documentCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Document display name. Required on create; editable.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "1–3 sentence summary of what this document is for (max 2,000 chars; null = none). Surfaced in list results so agents can discover a project's knowledge without fetching bodies. Set it when creating a document; keep it short — it is metadata, not a second body.", "example": "A concise description.", "examples": [ "A concise description." ] }, "projectId": { "type": "string", "minLength": 1, "description": "The project this document belongs to. Required on create — a document always lives in a project — and immutable afterwards.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true }, "parentDocumentId": { "type": [ "string", "null" ], "description": "The document this one is nested under — a parent in the same project. Set once at creation and immutable thereafter.", "example": "429XYeO6", "examples": [ "429XYeO6" ], "x-createOnly": true }, "folderId": { "type": [ "string", "null" ], "description": "The folder this document sits in — a document folder in the same project. Omit or send null to place it at the project root. The folder path is derived by the server. Set once at creation; moving a document between folders is not part of the update surface yet.", "example": "dBGa8nam", "examples": [ "dBGa8nam" ], "x-createOnly": true }, "accessType": { "type": "string", "enum": [ "public", "limited" ], "description": "Who can see this document. `public` (the default) — everyone in the project. `limited` — only the document's own member list, which starts out as JUST THE RESOLVED AUTHOR: when an agent or integration creates a limited document, the author it resolves to is the one who can reach it, not the caller. `private` — a legacy state the API cannot set; those documents are readable and filterable but cannot be created here. Choose this when you create the document — it cannot be changed afterwards through the API (change it in the Nifty app instead). A child document always inherits its parent's access type.", "example": "public", "examples": [ "public" ], "x-createOnly": true }, "content": { "type": "string", "description": "Initial document body, as Markdown. Supports headings, lists, tables, code blocks and Nifty mention syntax. Create-only: the body of an existing document is EXTENDED with the `append` operation and read back with the `content` operation — it can never be replaced or deleted, and it is not returned by list or get.", "example": "Looks good — shipping this today.", "examples": [ "Looks good — shipping this today." ], "x-createOnly": true }, "locked": { "type": "boolean", "description": "Whether the document is locked against edits.", "example": false, "examples": [ false ] }, "archived": { "type": "boolean", "description": "Whether the document is archived. Archived documents stay in the project but are hidden from default views. Independent of deletion — an archived document is not deleted, and a deleted document is not archived.", "example": false, "examples": [ false ] } }, "required": [ "name", "projectId" ], "additionalProperties": false }, "documentUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Document display name. Required on create; editable.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "maxLength": 2000, "description": "1–3 sentence summary of what this document is for (max 2,000 chars; null = none). Surfaced in list results so agents can discover a project's knowledge without fetching bodies. Set it when creating a document; keep it short — it is metadata, not a second body.", "example": "A concise description.", "examples": [ "A concise description." ] }, "locked": { "type": "boolean", "description": "Whether the document is locked against edits.", "example": false, "examples": [ false ] }, "archived": { "type": "boolean", "description": "Whether the document is archived. Archived documents stay in the project but are hidden from default views. Independent of deletion — an archived document is not deleted, and a deleted document is not archived.", "example": false, "examples": [ false ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "favorite": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "pzw41NKo", "examples": [ "pzw41NKo" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "name": { "type": "string", "description": "The label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.", "example": "Example", "examples": [ "Example" ] }, "type": { "type": "string", "enum": [ "project", "document", "file", "fileFolder", "documentFolder", "projectEmbed", "personalNotes", "personalTasks", "createdByMe" ], "description": "What kind of thing is favorited, and therefore what `resourceId` must point at: `project` (a project id, plus `projectId`), `document` (a document id), `file` (a file id), `fileFolder` / `documentFolder` (a folder id), `projectEmbed` (an embed id, plus `projectId`). `personalNotes`, `personalTasks` and `createdByMe` are standing personal views rather than a specific item — they take no `resourceId`. Set once: re-pointing a favorite means deleting it and creating another.", "example": "project", "examples": [ "project" ] }, "order": { "type": [ "number", "null" ], "description": "Rank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.", "example": 100, "examples": [ 100 ] }, "resourceId": { "type": [ "string", "null" ], "description": "The id of the favorited item. Required for every `type` except the three standing personal views (`personalNotes`, `personalTasks`, `createdByMe`), which take none. Set once — a favorite cannot be re-pointed.", "example": "Dd0fq2dw", "examples": [ "Dd0fq2dw" ] }, "projectId": { "type": [ "string", "null" ], "description": "The project a `project` or `projectEmbed` favorite lives in. Required on create for those two types and ignored for the rest. Set once — a favorite cannot be re-pointed.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "favoriteFolderId": { "type": [ "string", "null" ], "description": "Folder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.", "example": "HXamuWk4", "examples": [ "HXamuWk4" ] }, "memberId": { "type": "string", "minLength": 1, "description": "The team member this favorite belongs to. Set by the server from whoever is calling — you only ever see your own.", "readOnly": true, "example": "P3hYIKqK", "examples": [ "P3hYIKqK" ] } }, "required": [ "id", "createdAt", "name", "type", "memberId" ], "additionalProperties": true }, "favoriteExpanded": { "description": "A Favorite with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/favorite" }, { "type": "object", "properties": { "member": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=member`.", "x-example-omit": true }, "favoriteFolder": { "allOf": [ { "$ref": "#/components/schemas/favoriteFolder" } ], "description": "The related Favorite Folder, present only when you pass `?expand=favoriteFolder`.", "x-example-omit": true }, "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true } } } ] }, "favoriteCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "The label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Rank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.", "example": 100, "examples": [ 100 ] }, "type": { "type": "string", "enum": [ "project", "document", "file", "fileFolder", "documentFolder", "projectEmbed", "personalNotes", "personalTasks", "createdByMe" ], "description": "What kind of thing is favorited, and therefore what `resourceId` must point at: `project` (a project id, plus `projectId`), `document` (a document id), `file` (a file id), `fileFolder` / `documentFolder` (a folder id), `projectEmbed` (an embed id, plus `projectId`). `personalNotes`, `personalTasks` and `createdByMe` are standing personal views rather than a specific item — they take no `resourceId`. Set once: re-pointing a favorite means deleting it and creating another.", "example": "project", "examples": [ "project" ], "x-createOnly": true }, "resourceId": { "type": "string", "description": "The id of the favorited item. Required for every `type` except the three standing personal views (`personalNotes`, `personalTasks`, `createdByMe`), which take none. Set once — a favorite cannot be re-pointed.", "example": "Dd0fq2dw", "examples": [ "Dd0fq2dw" ], "x-createOnly": true }, "projectId": { "type": "string", "description": "The project a `project` or `projectEmbed` favorite lives in. Required for those two types, ignored for the rest.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true }, "favoriteFolderId": { "type": [ "string", "null" ], "description": "Folder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.", "example": "HXamuWk4", "examples": [ "HXamuWk4" ] } }, "required": [ "name", "type" ], "additionalProperties": false }, "favoriteUpdate": { "type": "object", "properties": { "name": { "type": "string", "description": "The label shown in the sidebar. It is a snapshot you supply, NOT a live mirror — rename the project and the favorite keeps the old label until you update it yourself.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Rank within the sidebar. Omit it on create to append at the end (the server assigns the next rank); supply one to place it explicitly. Settable on update for drag-and-drop reordering — pick a value between the two neighbours you are dropping between.", "example": 100, "examples": [ 100 ] }, "favoriteFolderId": { "type": [ "string", "null" ], "description": "Folder grouping this favorite. Null = top-level (not in any folder). Mutable — favorites move between folders.", "example": "HXamuWk4", "examples": [ "HXamuWk4" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "favoriteFolder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "HXamuWk4", "examples": [ "HXamuWk4" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "name": { "type": "string", "minLength": 1, "description": "Folder name shown in the sidebar. Capped at 30 characters, which is easy to hit.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": "integer", "description": "Rank within the sidebar. Omit it and the server appends the folder at the end.", "example": 100, "examples": [ 100 ] }, "createdById": { "type": "string", "minLength": 1, "description": "Team member who created this folder. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "EfcGKsYk", "examples": [ "EfcGKsYk" ] }, "updatedById": { "type": [ "string", "null" ], "description": "Team member who last updated this folder. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "ZJIkEsGm", "examples": [ "ZJIkEsGm" ] } }, "required": [ "id", "createdAt", "name", "order", "createdById" ], "additionalProperties": true }, "favoriteFolderExpanded": { "description": "A Favorite Folder with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/favoriteFolder" }, { "type": "object", "properties": { "createdBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=createdBy`.", "x-example-omit": true }, "updatedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=updatedBy`.", "x-example-omit": true } } } ] }, "favoriteFolderCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Folder name shown in the sidebar. Capped at 30 characters, which is easy to hit.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": "integer", "description": "Rank within the sidebar. Omit it and the server appends the folder at the end.", "example": 100, "examples": [ 100 ] } }, "required": [ "name" ], "additionalProperties": false }, "favoriteFolderUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Folder name shown in the sidebar. Capped at 30 characters, which is easy to hit.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": "integer", "description": "Rank within the sidebar. Omit it and the server appends the folder at the end.", "example": 100, "examples": [ 100 ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "file": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "xvM2toUM", "examples": [ "xvM2toUM" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "1IYoWAgA", "examples": [ "1IYoWAgA" ] }, "name": { "type": "string", "description": "File name, WITH its extension — there is no content-type field on a file, so the extension in this name is how a consumer tells a PDF from a PNG. 1–255 characters after trimming; a blank name is rejected.", "example": "Example", "examples": [ "Example" ] }, "size": { "type": "integer", "minimum": 0, "description": "Size of the uploaded file in bytes. Required on create — pass the byte count of what you uploaded. Maximum 2,147,483,646 (2 GB) per file, and the upload also has to fit your team's remaining storage quota; exceeding either is rejected.", "example": 20480, "examples": [ 20480 ] }, "url": { "type": "string", "description": "Time-limited download URL for the stored file. Read-only — set the bytes at creation with `uploadKey`; they never move afterwards.", "readOnly": true, "example": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "examples": [ "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf" ] }, "processed": { "type": "boolean", "description": "False until server-side post-processing (thumbnail generation, virus scanning) finishes — `thumbnail` and `download` may be null until then. Typically a few seconds.", "readOnly": true, "example": false, "examples": [ false ] }, "download": { "type": [ "string", "null" ], "description": "Alternate time-limited download URL for the same bytes as `url`. Read-only.", "readOnly": true, "example": "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf", "examples": [ "https://cdn.nifty.pm/xvM2toUM/quarterly-report.pdf" ] }, "thumbnail": { "type": [ "string", "null" ], "description": "Preview-image URL for image and video files; null for everything else, and null until `processed` becomes true. Read-only.", "readOnly": true, "example": "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png", "examples": [ "https://cdn.nifty.pm/thumb/xvM2toUM/quarterly-report.png" ] }, "folderStack": { "type": "array", "items": { "type": "string" }, "description": "The folder path this file sits in, from the project root down to its direct parent. Derived by the server from `folderId`.", "readOnly": true, "example": [ "BJemkA8N" ], "examples": [ [ "BJemkA8N" ] ] }, "subscribers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": true }, "description": "Team members subscribed to this file — they are notified when it changes. Populated only when you ask for it with `?expand=subscribers`; add and remove them with POST / DELETE `/files/{id}/subscribers`.", "example": [], "examples": [ [] ] }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": true }, "description": "Labels attached to this file. Populated only when you ask for it with `?expand=labels`; add and remove them with POST / DELETE `/files/{id}/labels`.", "example": [], "examples": [ [] ] }, "uploaderId": { "type": [ "string", "null" ], "description": "The team member who uploaded the file — a member id, so resolve it with `?expand=uploader` or `GET /members/{id}`. Null when uploaded by an agent or an integration — see `createdByActorType`.", "readOnly": true, "example": "FL6HICQe", "examples": [ "FL6HICQe" ] }, "projectId": { "type": [ "string", "null" ], "description": "Attach the file to this project. At least one of `projectId`, `taskId`, `documentId`, `messageId` or `folderId` is required on create. Fixed at upload.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "taskId": { "type": [ "string", "null" ], "description": "Attach the file to this task. At least one of `projectId`, `taskId`, `documentId`, `messageId` or `folderId` is required on create. Fixed at upload.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "documentId": { "type": [ "string", "null" ], "description": "Attach the file to this document. At least one of `projectId`, `taskId`, `documentId`, `messageId` or `folderId` is required on create. Fixed at upload.", "example": "ELe0nkum", "examples": [ "ELe0nkum" ] }, "messageId": { "type": [ "string", "null" ], "description": "Attach the file to this message. At least one of `projectId`, `taskId`, `documentId`, `messageId` or `folderId` is required on create. Fixed at upload.", "example": "4SsY67bC", "examples": [ "4SsY67bC" ] }, "folderId": { "type": [ "string", "null" ], "description": "Place the file in this folder. At least one of `projectId`, `taskId`, `documentId`, `messageId` or `folderId` is required on create. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.", "example": "dBGa8nam", "examples": [ "dBGa8nam" ] }, "annotationTaskId": { "type": [ "string", "null" ], "description": "The task that holds this file's annotation thread, created when the file is opened in annotation mode. Read-only.", "readOnly": true, "example": "fV4pUGI6", "examples": [ "fV4pUGI6" ] } }, "required": [ "id", "createdAt", "name", "size", "url" ], "additionalProperties": true }, "fileExpanded": { "description": "A File with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/file" }, { "type": "object", "properties": { "uploader": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=uploader`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "document": { "allOf": [ { "$ref": "#/components/schemas/document" } ], "description": "The related Document, present only when you pass `?expand=document`.", "x-example-omit": true }, "message": { "allOf": [ { "$ref": "#/components/schemas/message" } ], "description": "The related Message, present only when you pass `?expand=message`.", "x-example-omit": true }, "annotationTask": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=annotationTask`.", "x-example-omit": true }, "annotations": { "type": "array", "items": { "$ref": "#/components/schemas/annotation" }, "description": "The linked Annotation rows, present only when you pass `?expand=annotations`.", "x-example-omit": true } } } ] }, "fileCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name, WITH its extension — there is no content-type field, so the extension is how a consumer tells a PDF from a PNG.", "example": "Example", "examples": [ "Example" ] }, "size": { "type": "integer", "minimum": 0, "maximum": 2147483646, "description": "Size of the uploaded file in bytes. Required — pass the byte count of what you uploaded. Maximum 2 GB per file, and the upload also has to fit your team's remaining storage quota.", "example": 20480, "examples": [ 20480 ] }, "uploadKey": { "type": "string", "description": "Storage key of the already-uploaded bytes: call the createUploadUrl operation, PUT the bytes to the presigned URL it returns, then pass its `uploadKey` here verbatim. Create REGISTERS metadata; it does not upload bytes.", "example": "Example upload key", "examples": [ "Example upload key" ], "x-createOnly": true }, "projectId": { "type": [ "string", "null" ], "description": "Attach the file to this project (one context per file).", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true }, "taskId": { "type": [ "string", "null" ], "description": "Attach the file to this task (one context per file).", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ], "x-createOnly": true }, "documentId": { "type": [ "string", "null" ], "description": "Attach the file to this document (one context per file).", "example": "ELe0nkum", "examples": [ "ELe0nkum" ], "x-createOnly": true }, "messageId": { "type": [ "string", "null" ], "description": "Attach the file to this message (one context per file).", "example": "4SsY67bC", "examples": [ "4SsY67bC" ], "x-createOnly": true }, "folderId": { "type": [ "string", "null" ], "description": "Place the file in this folder. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.", "example": "dBGa8nam", "examples": [ "dBGa8nam" ] } }, "required": [ "name", "size", "uploadKey" ], "additionalProperties": false, "anyOf": [ { "required": [ "projectId" ] }, { "required": [ "taskId" ] }, { "required": [ "documentId" ] }, { "required": [ "messageId" ] }, { "required": [ "folderId" ] } ] }, "fileUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "File name, WITH its extension — there is no content-type field, so the extension is how a consumer tells a PDF from a PNG.", "example": "Example", "examples": [ "Example" ] }, "size": { "type": "integer", "minimum": 0, "maximum": 2147483646, "description": "Size of the uploaded file in bytes. Required — pass the byte count of what you uploaded. Maximum 2 GB per file, and the upload also has to fit your team's remaining storage quota.", "example": 20480, "examples": [ 20480 ] }, "folderId": { "type": [ "string", "null" ], "description": "Place the file in this folder. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.", "example": "dBGa8nam", "examples": [ "dBGa8nam" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "form": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "Jt0ByAIi", "examples": [ "Jt0ByAIi" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "Xv6FM6n4", "examples": [ "Xv6FM6n4" ] }, "name": { "type": [ "string", "null" ], "description": "The form's name, shown to respondents as its title. Set it with `meta.title`.", "readOnly": true, "example": "Example", "examples": [ "Example" ] }, "automation": { "type": [ "string", "null" ], "enum": [ "task", "doc", "message", "checkin" ], "description": "What Nifty does when the form is submitted: `task` creates a task, `doc` a document, `message` a chat message, `checkin` a check-in response. null for a plain form that just records answers. When it is `task`, both `targetStatusId` and `targetListId` are required in the same request.", "example": "task", "examples": [ "task" ] }, "targetStatusId": { "type": [ "string", "null" ], "description": "The board column a `task` automation files its new task into. Required whenever `automation` is `task`.", "example": "00taIogS", "examples": [ "00taIogS" ] }, "targetListId": { "type": [ "string", "null" ], "description": "The list a `task` automation files its new task into. Required whenever `automation` is `task`.", "example": "s7BA8vsY", "examples": [ "s7BA8vsY" ] }, "meta": { "type": [ "object", "null" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true, "description": "The form's display metadata. `title` is the form's name, shown to respondents (also surfaced read-only as `name`); `description` is the blurb under it.", "example": {}, "examples": [ {} ] }, "success": { "type": [ "object", "null" ], "properties": { "title": { "type": "string", "description": "Heading shown to a respondent after they submit." }, "description": { "type": "string", "description": "Body text shown under the heading." }, "image": { "type": "string", "description": "URL of an image shown on the confirmation screen. Server-set from an upload made in the Nifty app — there is no upload endpoint on this API, so treat it as read-only." }, "redirect_url": { "type": "string", "description": "Send respondents here instead of showing the confirmation screen. Note the snake_case key: this object is stored verbatim as JSON." }, "email": { "type": "object", "properties": { "email_field_fe_id": { "type": "string", "description": "The `clientKey` of the form field holding the respondent's email address — that is where the reply is sent." }, "subject": { "type": "string", "description": "Subject line of the reply." }, "content": { "type": "string", "description": "Body of the reply." } }, "additionalProperties": true, "description": "Auto-reply emailed to the respondent after they submit." } }, "additionalProperties": true, "description": "What a respondent sees after submitting: a heading, body text, an optional image, an optional redirect, and an optional auto-reply email. Stored verbatim, so its keys are snake_case unlike the rest of this API.", "example": {}, "examples": [ {} ] }, "multiSubmit": { "type": [ "boolean", "null" ], "description": "Whether one respondent may submit the form more than once. Defaults to false.", "example": false, "examples": [ false ] }, "docAccessType": { "type": [ "string", "null" ], "enum": [ "public", "limited", "private" ], "description": "Who can see the document a `doc` automation creates: `public` (the whole team), `limited` (invited members), `private` (the author only). Defaults to `public`.", "example": "public", "examples": [ "public" ] }, "url": { "type": [ "string", "null" ], "description": "The public link respondents open to fill this form in. Null until the form has been shared.", "readOnly": true, "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "projectId": { "type": [ "string", "null" ], "description": "An optional project to associate this form with. It does not affect who can see the form — forms are visible across the whole workspace.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "createdById": { "type": [ "string", "null" ], "description": "Team member who created this form — a member id, so resolve it with `GET /members/{id}`. Read-only, set from the caller. Null for creates that have no member behind them.", "readOnly": true, "example": "Qf8HggwY", "examples": [ "Qf8HggwY" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text", "textarea", "dropdown", "checkboxes", "number", "date", "file", "email" ] }, "label": { "type": "string" }, "required": { "type": [ "boolean", "null" ] }, "useAsTaskName": { "type": [ "boolean", "null" ] }, "order": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "clientKey": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "randomize": { "type": [ "boolean", "null" ] }, "withOther": { "type": [ "boolean", "null" ] }, "taskField": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Id of the target — a custom-field id for a custom-field target." }, "type": { "type": "string", "description": "Which task property the answer fills in." } }, "additionalProperties": true }, "condition": { "type": [ "object", "null" ], "properties": { "field_fe_id": { "type": "string", "description": "The `clientKey` of the field whose answer is tested. Note the snake_case key: this object is stored verbatim as JSON." }, "type": { "type": "string", "enum": [ "eq", "neq", "contains", "ncontains", "gt", "lt", "selected", "nselected", "populated", "npopulated" ], "description": "How the other field's answer is compared to `value`." }, "value": { "type": "string", "description": "The value compared against. Ignored by `populated` and `npopulated`." } }, "additionalProperties": true }, "statusCondition": { "type": [ "object", "null" ], "properties": { "resource_type": { "type": "string", "description": "What the two ids below point at." }, "match_resource_id": { "type": "string", "description": "Used when the answer matches the condition." }, "no_match_resource_id": { "type": "string", "description": "Used when the answer does not match." }, "value": { "type": "string", "description": "The value compared against." }, "type": { "type": "string", "enum": [ "eq", "neq", "contains", "ncontains", "gt", "lt", "selected", "nselected", "populated", "npopulated" ], "description": "How the field's answer is compared to `value`." } }, "additionalProperties": true }, "listCondition": { "type": [ "object", "null" ], "properties": { "resource_type": { "type": "string", "description": "What the two ids below point at." }, "match_resource_id": { "type": "string", "description": "Used when the answer matches the condition." }, "no_match_resource_id": { "type": "string", "description": "Used when the answer does not match." }, "value": { "type": "string", "description": "The value compared against." }, "type": { "type": "string", "enum": [ "eq", "neq", "contains", "ncontains", "gt", "lt", "selected", "nselected", "populated", "npopulated" ], "description": "How the field's answer is compared to `value`." } }, "additionalProperties": true }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "value": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "value" ], "additionalProperties": false } } }, "required": [ "id", "type", "label" ], "additionalProperties": false }, "description": "The form's questions, in the order respondents see them. **This is a full replacement**: any existing field missing from the array is deleted, along with its options and any answers already submitted to it — include each field's `id` to keep it. Omit the key entirely to leave the questions untouched. Cannot be an empty array (a form keeps at least one question), and cannot exceed 200 fields.", "example": [], "examples": [ [] ] } }, "required": [ "id", "createdAt" ], "additionalProperties": true }, "formExpanded": { "description": "A Form with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/form" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true } } } ] }, "goal": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "AdESgais", "examples": [ "AdESgais" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "description": "Goal name", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional longer description", "example": "A concise description.", "examples": [ "A concise description." ] }, "accessType": { "type": "string", "enum": [ "public", "limited", "private" ], "description": "Who can see this goal: `public` (the whole team), `limited` (the team members listed in `members`), `private` (the owner only).", "example": "public", "examples": [ "public" ] }, "goalSourceType": { "type": "string", "enum": [ "customField", "manual", "label", "assigneeLabel", "assignee" ], "description": "What feeds the goal's task set: `customField`, `manual`, `label`, `assigneeLabel`, `assignee`.", "example": "customField", "examples": [ "customField" ] }, "trackMetricType": { "type": "string", "enum": [ "taskCount", "trackedTime", "customFieldValue", "storyPoints" ], "description": "How progress is measured: `taskCount`, `trackedTime`, `customFieldValue`, `storyPoints`.", "example": "taskCount", "examples": [ "taskCount" ] }, "targetType": { "type": "string", "enum": [ "dynamic", "static" ], "description": "Target mode: `dynamic` (the target tracks the live total of the goal task set) or `static` (a fixed `targetValue`).", "example": "dynamic", "examples": [ "dynamic" ] }, "goalSourceValue": { "type": [ "string", "null" ], "description": "The id `goalSourceType` points at: for `label` a label id; for `customField` a custom-field id; for `assignee` and `assigneeLabel` a team-member id. Not used when `goalSourceType` is `manual` (send the task ids in `tasks` instead).", "example": "Example goal source value", "examples": [ "Example goal source value" ] }, "goalSourceOption": { "type": [ "string", "null" ], "description": "Narrows `goalSourceValue` when `goalSourceType` is `custom_field`: the id of the dropdown option to match. Ignored for every other source type.", "example": "Example goal source option", "examples": [ "Example goal source option" ] }, "trackMetricValue": { "type": [ "string", "null" ], "description": "The id `trackMetricType` points at — for `custom_field_value`, the custom-field id whose values are summed. Not used by the other metric types.", "example": "Example track metric value", "examples": [ "Example track metric value" ] }, "targetValue": { "type": "number", "description": "The fixed numeric target. Used only when `targetType` is `static`; when `targetType` is `dynamic` it is recomputed by the server from the goal task set and anything you send is overwritten.", "example": 100, "examples": [ 100 ] }, "progressTotal": { "type": "number", "description": "Persisted denominator of the progress rollup (float).", "readOnly": true, "example": 100, "examples": [ 100 ] }, "progressCompleted": { "type": "number", "description": "Persisted numerator of the progress rollup (float).", "readOnly": true, "example": 100, "examples": [ 100 ] }, "endAt": { "type": "string", "format": "date-time", "description": "Target completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this goal was completed, or null while it is open. Entirely server-derived: it is stamped the moment `progressCompleted` reaches `progressTotal` and cleared again if progress falls back below. There is no manual complete or reopen — finish the tracked work, or lower a `static` `targetValue`.", "readOnly": true, "example": "2026-06-03T12:00:00.000Z", "examples": [ "2026-06-03T12:00:00.000Z" ] }, "teamId": { "type": "string", "minLength": 1, "description": "The workspace (team) this goal belongs to.", "readOnly": true, "example": "cfC83TeS", "examples": [ "cfC83TeS" ] }, "ownerId": { "type": [ "string", "null" ], "minLength": 1, "description": "The team member who owns this goal — for a `private` goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.", "example": "QpCuKyI2", "examples": [ "QpCuKyI2" ] }, "goalGroupId": { "type": [ "string", "null" ], "minLength": 1, "description": "Goal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit `null` unlinks; omitted leaves it unchanged.", "example": "pPAcKseY", "examples": [ "pPAcKseY" ] } }, "required": [ "id", "createdAt", "name", "accessType", "goalSourceType", "trackMetricType", "targetType", "targetValue", "progressTotal", "progressCompleted", "endAt", "teamId" ], "additionalProperties": true }, "goalExpanded": { "description": "A Goal with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/goal" }, { "type": "object", "properties": { "owner": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=owner`.", "x-example-omit": true }, "goalGroup": { "allOf": [ { "$ref": "#/components/schemas/goalGroup" } ], "description": "The related Goal Group, present only when you pass `?expand=goalGroup`.", "x-example-omit": true }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=members`.", "x-example-omit": true }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The linked Task rows, present only when you pass `?expand=tasks`.", "x-example-omit": true }, "lists": { "type": "array", "items": { "$ref": "#/components/schemas/list" }, "description": "The linked List rows, present only when you pass `?expand=lists`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "goalCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Goal name", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional longer description", "example": "A concise description.", "examples": [ "A concise description." ] }, "accessType": { "type": "string", "enum": [ "public", "limited", "private" ], "description": "Who can see this goal: `public` (the whole team), `limited` (the team members listed in `members`), `private` (the owner only).", "example": "public", "examples": [ "public" ] }, "endAt": { "type": "string", "format": "date-time", "description": "Target completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "goalGroupId": { "type": [ "string", "null" ], "minLength": 1, "description": "Goal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit `null` unlinks; omitted leaves it unchanged.", "example": "pPAcKseY", "examples": [ "pPAcKseY" ] }, "members": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members this goal is shared with (this is who `accessType: limited` means). Set when the goal is created; ignored on update. Read them back with `?expand=members`.", "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ], "x-createOnly": true }, "goalSourceType": { "type": "string", "enum": [ "customField", "manual", "label", "assigneeLabel", "assignee" ], "description": "What feeds the goal's task set: `customField`, `manual`, `label`, `assigneeLabel`, `assignee`.", "example": "customField", "examples": [ "customField" ] }, "goalSourceValue": { "type": [ "string", "null" ], "description": "The id `goalSourceType` points at: for `label` a label id; for `customField` a custom-field id; for `assignee` and `assigneeLabel` a team-member id. Not used when `goalSourceType` is `manual` (send the task ids in `tasks` instead).", "example": "Example goal source value", "examples": [ "Example goal source value" ] }, "goalSourceOption": { "type": [ "string", "null" ], "description": "Narrows `goalSourceValue` when `goalSourceType` is `custom_field`: the id of the dropdown option to match. Ignored for every other source type.", "example": "Example goal source option", "examples": [ "Example goal source option" ] }, "tasks": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Tasks linked to this goal, for goals whose `goalSourceType` is `manual`. Set when the goal is created; ignored on update. Read them back with `?expand=tasks`.", "example": [ "KfS0ha8P" ], "examples": [ [ "KfS0ha8P" ] ], "x-createOnly": true }, "lists": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Lists whose tasks feed this goal. Set when the goal is created; ignored on update. Read them back with `?expand=lists`.", "example": [ "lN6ZQycO" ], "examples": [ [ "lN6ZQycO" ] ], "x-createOnly": true }, "trackMetricType": { "type": "string", "enum": [ "taskCount", "trackedTime", "customFieldValue", "storyPoints" ], "description": "How progress is measured: `taskCount`, `trackedTime`, `customFieldValue`, `storyPoints`.", "example": "taskCount", "examples": [ "taskCount" ] }, "trackMetricValue": { "type": [ "string", "null" ], "description": "The id `trackMetricType` points at — for `custom_field_value`, the custom-field id whose values are summed. Not used by the other metric types.", "example": "Example track metric value", "examples": [ "Example track metric value" ] }, "targetType": { "type": "string", "enum": [ "dynamic", "static" ], "description": "Target mode: `dynamic` (the target tracks the live total of the goal task set) or `static` (a fixed `targetValue`).", "example": "dynamic", "examples": [ "dynamic" ] }, "targetValue": { "type": "number", "description": "The fixed numeric target. Used only when `targetType` is `static`; when `targetType` is `dynamic` it is recomputed by the server from the goal task set and anything you send is overwritten.", "example": 100, "examples": [ 100 ] }, "ownerId": { "type": [ "string", "null" ], "minLength": 1, "description": "The team member who owns this goal — for a `private` goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.", "example": "QpCuKyI2", "examples": [ "QpCuKyI2" ] } }, "required": [ "name", "endAt" ], "additionalProperties": false }, "goalUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Goal name", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional longer description", "example": "A concise description.", "examples": [ "A concise description." ] }, "accessType": { "type": "string", "enum": [ "public", "limited", "private" ], "description": "Who can see this goal: `public` (the whole team), `limited` (the team members listed in `members`), `private` (the owner only).", "example": "public", "examples": [ "public" ] }, "endAt": { "type": "string", "format": "date-time", "description": "Target completion date (ISO 8601). Required on create; a goal always has a date it is aiming at.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "goalGroupId": { "type": [ "string", "null" ], "minLength": 1, "description": "Goal group this goal is filed under (nullable — ON DELETE SET NULL). Writable: an id files the goal under that group; explicit `null` unlinks; omitted leaves it unchanged.", "example": "pPAcKseY", "examples": [ "pPAcKseY" ] }, "goalSourceType": { "type": "string", "enum": [ "customField", "manual", "label", "assigneeLabel", "assignee" ], "description": "What feeds the goal's task set: `customField`, `manual`, `label`, `assigneeLabel`, `assignee`.", "example": "customField", "examples": [ "customField" ] }, "goalSourceValue": { "type": [ "string", "null" ], "description": "The id `goalSourceType` points at: for `label` a label id; for `customField` a custom-field id; for `assignee` and `assigneeLabel` a team-member id. Not used when `goalSourceType` is `manual` (send the task ids in `tasks` instead).", "example": "Example goal source value", "examples": [ "Example goal source value" ] }, "goalSourceOption": { "type": [ "string", "null" ], "description": "Narrows `goalSourceValue` when `goalSourceType` is `custom_field`: the id of the dropdown option to match. Ignored for every other source type.", "example": "Example goal source option", "examples": [ "Example goal source option" ] }, "trackMetricType": { "type": "string", "enum": [ "taskCount", "trackedTime", "customFieldValue", "storyPoints" ], "description": "How progress is measured: `taskCount`, `trackedTime`, `customFieldValue`, `storyPoints`.", "example": "taskCount", "examples": [ "taskCount" ] }, "trackMetricValue": { "type": [ "string", "null" ], "description": "The id `trackMetricType` points at — for `custom_field_value`, the custom-field id whose values are summed. Not used by the other metric types.", "example": "Example track metric value", "examples": [ "Example track metric value" ] }, "targetType": { "type": "string", "enum": [ "dynamic", "static" ], "description": "Target mode: `dynamic` (the target tracks the live total of the goal task set) or `static` (a fixed `targetValue`).", "example": "dynamic", "examples": [ "dynamic" ] }, "targetValue": { "type": "number", "description": "The fixed numeric target. Used only when `targetType` is `static`; when `targetType` is `dynamic` it is recomputed by the server from the goal task set and anything you send is overwritten.", "example": 100, "examples": [ 100 ] }, "ownerId": { "type": [ "string", "null" ], "minLength": 1, "description": "The team member who owns this goal — for a `private` goal, the only member who can see it. Defaults to the caller on create; send another team member id to hand it over.", "example": "QpCuKyI2", "examples": [ "QpCuKyI2" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "goalGroup": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "pPAcKseY", "examples": [ "pPAcKseY" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "description": "Display name for this goal group. 1–100 characters; a blank name is rejected.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": "string", "description": "Free-text description of the group. Send `null` or `\"\"` to clear it; it always reads back as a string, empty when unset.", "example": "A concise description.", "examples": [ "A concise description." ] } }, "required": [ "id", "createdAt", "name", "description" ], "additionalProperties": true }, "goalGroupExpanded": { "description": "A Goal Group with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/goalGroup" }, { "type": "object", "properties": { "goals": { "type": "array", "items": { "$ref": "#/components/schemas/goal" }, "description": "The linked Goal rows, present only when you pass `?expand=goals`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true } } } ] }, "goalGroupCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for this goal group. 1–100 characters; a blank name is rejected.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Free-text description of the group. Send `null` or `\"\"` to clear it; it always reads back as a string, empty when unset.", "example": "A concise description.", "examples": [ "A concise description." ] } }, "required": [ "name" ], "additionalProperties": false }, "goalGroupUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for this goal group. 1–100 characters; a blank name is rejected.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Free-text description of the group. Send `null` or `\"\"` to clear it; it always reads back as a string, empty when unset.", "example": "A concise description.", "examples": [ "A concise description." ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "label": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "xbUMIqgS", "examples": [ "xbUMIqgS" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Team member who moved this label to the trash. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "7ESqMCCu", "examples": [ "7ESqMCCu" ] }, "name": { "type": [ "string", "null" ], "description": "The label text. Send at least one of `name` or `color` when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.", "example": "Example", "examples": [ "Example" ] }, "color": { "type": [ "string", "null" ], "description": "Hex color, `#RGB` or `#RRGGBB`. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so `#00A99B` reads back as `#00a99b`. Send at least one of `name` or `color` when creating a label.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "default": { "type": "boolean", "description": "True for the labels Nifty seeds into a workspace. Server-managed, and those labels are protected: renaming or deleting one returns 403.", "readOnly": true, "example": false, "examples": [ false ] }, "type": { "type": "string", "enum": [ "others", "member" ], "description": "What the label is for: `others` for an ordinary tag, `member` for the labels used to group people. Defaults to `others`, and cannot be changed afterwards.", "example": "others", "examples": [ "others" ] } }, "required": [ "id", "createdAt", "name", "color", "default", "type" ], "additionalProperties": true }, "labelExpanded": { "description": "A Label with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/label" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true } } } ] }, "labelCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "The label text. Send at least one of `name` or `color` when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.", "example": "Example", "examples": [ "Example" ] }, "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$", "description": "Hex color, `#RGB` or `#RRGGBB`. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so `#00A99B` reads back as `#00a99b`. Send at least one of `name` or `color` when creating a label.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "type": { "type": "string", "enum": [ "others", "member" ], "description": "What the label is for: `others` for an ordinary tag, `member` for the labels used to group people. Defaults to `others`, and cannot be changed afterwards.", "example": "others", "examples": [ "others" ], "x-createOnly": true } }, "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "color" ] } ] }, "labelUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "The label text. Send at least one of `name` or `color` when creating a label — an empty body is rejected. Names are unique per workspace among live labels: reusing one returns 409.", "example": "Example", "examples": [ "Example" ] }, "color": { "type": "string", "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$", "description": "Hex color, `#RGB` or `#RRGGBB`. Omit it and the server assigns a random palette color, so a label always has one. Stored lowercase and expanded to 6 digits, so `#00A99B` reads back as `#00a99b`. Send at least one of `name` or `color` when creating a label.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "list": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "lN6ZQycO", "examples": [ "lN6ZQycO" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "archived": { "type": "boolean", "description": "Whether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.", "example": false, "examples": [ false ] }, "name": { "type": [ "string", "null" ], "description": "List name. Trimmed; obvious spam is rejected with 400. Null only on lists created before this API existed.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "List description", "example": "A concise description.", "examples": [ "A concise description." ] }, "start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start date (ISO 8601). **Required together with `end` whenever `isMilestone` is true** — including when flipping it true with a PATCH. `end` must be at least 2 days after `start`; use a task with a due date for single-day work. Forced to null when `isMilestone` is false.", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "End date (ISO 8601). **Required together with `start` whenever `isMilestone` is true** — including when flipping it true with a PATCH. Must be at least 2 days after `start`; use a task with a due date for single-day work. Forced to null when `isMilestone` is false.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.", "example": 100, "examples": [ 100 ] }, "color": { "type": [ "string", "null" ], "description": "Hex color, `#RGB` or `#RRGGBB`. Stored lowercase and expanded to 6 digits, so `#0A9` reads back as `#00aa99`. Omitted on create → the server assigns a random palette color, so a list always has one.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "isMilestone": { "type": "boolean", "description": "false (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires `start` and `end` at least 2 days apart.", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this list belongs to (scope). Immutable after creation.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "dependencyId": { "type": [ "string", "null" ], "description": "Id of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.", "example": "i9TUmOWm", "examples": [ "i9TUmOWm" ] }, "statusId": { "type": [ "string", "null" ], "description": "When set, this list also appears as a column on the project board, backed by the given status. Cannot be changed after creation.", "example": "5aM4ncwI", "examples": [ "5aM4ncwI" ] } }, "required": [ "id", "createdAt", "projectId" ], "additionalProperties": true }, "listExpanded": { "description": "A List with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/list" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "dependency": { "allOf": [ { "$ref": "#/components/schemas/list" } ], "description": "The related List, present only when you pass `?expand=dependency`.", "x-example-omit": true }, "recurringRule": { "allOf": [ { "$ref": "#/components/schemas/recurringRule" } ], "description": "The related Recurring Rule, present only when you pass `?expand=recurringRule`.", "x-example-omit": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/status" } ], "description": "The related Status, present only when you pass `?expand=status`.", "x-example-omit": true }, "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=assignees`.", "x-example-omit": true }, "hiddenFor": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The linked Role rows, present only when you pass `?expand=hiddenFor`.", "x-example-omit": true }, "goals": { "type": "array", "items": { "$ref": "#/components/schemas/goal" }, "description": "The linked Goal rows, present only when you pass `?expand=goals`.", "x-example-omit": true }, "customFields": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The linked attachedCustomField rows, present only when you pass `?expand=customFields`.", "x-example-omit": true }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The linked Task rows, present only when you pass `?expand=tasks`.", "x-example-omit": true } } } ] }, "listCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "List name. Trimmed; obvious spam is rejected with 400.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "List description", "example": "A concise description.", "examples": [ "A concise description." ] }, "start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start date (ISO 8601). **Required together with `end` whenever `isMilestone` is true** — including when flipping it true with a PATCH. `end` must be at least 2 days after `start`; use a task with a due date for single-day work. Forced to null when `isMilestone` is false.", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "End date (ISO 8601). **Required together with `start` whenever `isMilestone` is true** — including when flipping it true with a PATCH. Must be at least 2 days after `start`; use a task with a due date for single-day work. Forced to null when `isMilestone` is false.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.", "example": 100, "examples": [ 100 ] }, "color": { "type": [ "string", "null" ], "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$", "description": "Hex color, `#RGB` or `#RRGGBB`. Stored lowercase and expanded to 6 digits, so `#0A9` reads back as `#00aa99`. Omitted on create → the server assigns a random palette color, so a list always has one.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "archived": { "type": "boolean", "description": "Whether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.", "example": false, "examples": [ false ] }, "isMilestone": { "type": "boolean", "description": "false (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires `start` and `end` at least 2 days apart.", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this list belongs to (scope). Immutable after creation.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true }, "dependencyId": { "type": [ "string", "null" ], "description": "Id of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.", "example": "i9TUmOWm", "examples": [ "i9TUmOWm" ] }, "statusId": { "type": [ "string", "null" ], "description": "When set, this list also appears as a column on the project board, backed by the given status. Cannot be changed after creation.", "example": "5aM4ncwI", "examples": [ "5aM4ncwI" ], "x-createOnly": true }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members assigned to this list. Replaces the whole set on update; use `POST`/`DELETE /lists/{id}/assignees` for a single add/remove.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] }, "hiddenFor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Roles this list is hidden from. Replaces the whole set on update; use `POST /lists/{id}/hidden-for` and `POST /lists/{id}/hidden-for/remove` for a single add/remove. Every id must be a role in the same workspace.", "example": [ "eN87BSak" ], "examples": [ [ "eN87BSak" ] ] }, "goals": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Goals this list contributes toward. Replaces the whole set on update; use `POST`/`DELETE /lists/{id}/goals` for a single add/remove.", "example": [ "AdESgais" ], "examples": [ [ "AdESgais" ] ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Set custom-field values on this list. Each entry is `{ customFieldId, value }` and `value` is always a string — send `\"\"` to clear one. Max 50 entries per request. Read them back with `?expand=customFields`.", "example": [], "examples": [ [] ] } }, "required": [ "name", "projectId" ], "additionalProperties": false }, "listUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "List name. Trimmed; obvious spam is rejected with 400.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "List description", "example": "A concise description.", "examples": [ "A concise description." ] }, "start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start date (ISO 8601). **Required together with `end` whenever `isMilestone` is true** — including when flipping it true with a PATCH. `end` must be at least 2 days after `start`; use a task with a due date for single-day work. Forced to null when `isMilestone` is false.", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "End date (ISO 8601). **Required together with `start` whenever `isMilestone` is true** — including when flipping it true with a PATCH. Must be at least 2 days after `start`; use a task with a due date for single-day work. Forced to null when `isMilestone` is false.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order within the project timeline. Server-defaulted to MAX(order)+100 when omitted on create.", "example": 100, "examples": [ 100 ] }, "color": { "type": [ "string", "null" ], "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$", "description": "Hex color, `#RGB` or `#RRGGBB`. Stored lowercase and expanded to 6 digits, so `#0A9` reads back as `#00aa99`. Omitted on create → the server assigns a random palette color, so a list always has one.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "archived": { "type": "boolean", "description": "Whether this list is archived (hidden from the active timeline but preserved). Regular field, NOT a soft-delete.", "example": false, "examples": [ false ] }, "isMilestone": { "type": "boolean", "description": "false (the default) = a flat list of tasks. true = a date-spanning milestone shown on the roadmap; it requires `start` and `end` at least 2 days apart.", "example": false, "examples": [ false ] }, "dependencyId": { "type": [ "string", "null" ], "description": "Id of the list that must finish before this one starts (timeline dependency). The target must belong to the same project, otherwise the request is rejected with 400.", "example": "i9TUmOWm", "examples": [ "i9TUmOWm" ] }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team members assigned to this list. Replaces the whole set on update; use `POST`/`DELETE /lists/{id}/assignees` for a single add/remove.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] }, "hiddenFor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Roles this list is hidden from. Replaces the whole set on update; use `POST /lists/{id}/hidden-for` and `POST /lists/{id}/hidden-for/remove` for a single add/remove. Every id must be a role in the same workspace.", "example": [ "eN87BSak" ], "examples": [ [ "eN87BSak" ] ] }, "goals": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Goals this list contributes toward. Replaces the whole set on update; use `POST`/`DELETE /lists/{id}/goals` for a single add/remove.", "example": [ "AdESgais" ], "examples": [ [ "AdESgais" ] ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Set custom-field values on this list. Each entry is `{ customFieldId, value }` and `value` is always a string — send `\"\"` to clear one. Max 50 entries per request. Read them back with `?expand=customFields`.", "example": [], "examples": [ [] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "member": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Team-member id (primary key)", "readOnly": true, "example": "P3hYIKqK", "examples": [ "P3hYIKqK" ] }, "userId": { "type": [ "string", "null" ], "minLength": 1, "description": "The global user-account id behind this member. Not resolvable through this API — `id` is what every other resource references.", "readOnly": true, "example": "EF6LMc0F", "examples": [ "EF6LMc0F" ] }, "name": { "type": [ "string", "null" ], "description": "Member's display name", "example": "Example", "examples": [ "Example" ] }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Member's email address.", "example": "jane@acme.com", "examples": [ "jane@acme.com" ] }, "avatar": { "type": [ "string", "null" ], "description": "Avatar image URL.", "readOnly": true, "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": [ "string", "null" ], "description": "Two-letter initials, shown when there is no avatar.", "readOnly": true, "example": "NB", "examples": [ "NB" ] }, "color": { "type": [ "string", "null" ], "description": "Hex tint used for this member's avatar placeholder.", "readOnly": true, "example": "#00A99B", "examples": [ "#00A99B" ] }, "online": { "type": [ "boolean", "null" ], "description": "Whether the member was connected at the moment this response was built. Point-in-time only; it is not pushed to you.", "readOnly": true, "example": false, "examples": [ false ] }, "tzIana": { "type": [ "string", "null" ], "description": "IANA timezone, for example \"America/Los_Angeles\".", "readOnly": true, "example": "America/New_York", "examples": [ "America/New_York" ] }, "pending": { "type": [ "boolean", "null" ], "description": "True while the member has been invited but has not accepted yet. An active member has `pending: false` and `removed: false`.", "readOnly": true, "example": false, "examples": [ false ] }, "removed": { "type": [ "boolean", "null" ], "description": "True once the member has been removed from the team. Members are removed, not soft-deleted: there is no `purgeAt` and no restore window, though inviting the same email again reactivates the original record.", "readOnly": true, "example": false, "examples": [ false ] }, "roleId": { "type": [ "string", "null" ], "description": "The member's role, which decides what they may do. Changing it re-roles the member and can cascade permission changes across the workspace; it requires the `editRole` permission. A role name (for example `manager`) is accepted in place of an id.", "example": "zngY4nUy", "examples": [ "zngY4nUy" ] }, "theme": { "type": [ "string", "null" ], "enum": [ "light", "dark", "fullLight" ], "description": "The colour theme this member sees in the Nifty app. Writable only on your own member record — writing another member's returns 403 whatever your role.", "example": "light", "examples": [ "light" ] }, "storyPointsCapacity": { "type": [ "number", "null" ], "description": "How many story points this member is expected to carry in a sprint. Writable only on your own member record.", "example": 100, "examples": [ 100 ] } }, "required": [ "id" ], "additionalProperties": true }, "memberExpanded": { "description": "A Team Member with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/member" }, { "type": "object", "properties": { "customFields": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The linked attachedCustomField rows, present only when you pass `?expand=customFields`.", "x-example-omit": true } } } ] }, "memberCreate": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Member's email address.", "example": "jane@acme.com", "examples": [ "jane@acme.com" ], "x-createOnly": true }, "name": { "type": "string", "description": "The invited person's display name. Defaults to the email address when omitted.", "example": "Example", "examples": [ "Example" ], "x-createOnly": true }, "roleId": { "type": "string", "minLength": 1, "description": "The member's role, which decides what they may do. Changing it re-roles the member and can cascade permission changes across the workspace; it requires the `editRole` permission. A role name (for example `manager`) is accepted in place of an id.", "example": "zngY4nUy", "examples": [ "zngY4nUy" ] }, "projectId": { "type": "string", "minLength": 1, "description": "Optionally add the invited member to this project at invite time.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true } }, "required": [ "email" ], "additionalProperties": false }, "memberUpdate": { "type": "object", "properties": { "roleId": { "type": "string", "minLength": 1, "description": "The member's role, which decides what they may do. Changing it re-roles the member and can cascade permission changes across the workspace; it requires the `editRole` permission. A role name (for example `manager`) is accepted in place of an id.", "example": "zngY4nUy", "examples": [ "zngY4nUy" ] }, "theme": { "type": "string", "enum": [ "light", "dark", "fullLight" ], "description": "The colour theme this member sees in the Nifty app. Writable only on your own member record — writing another member's returns 403 whatever your role.", "example": "light", "examples": [ "light" ], "x-updateOnly": true }, "storyPointsCapacity": { "type": "number", "description": "How many story points this member is expected to carry in a sprint. Writable only on your own member record.", "example": 100, "examples": [ 100 ], "x-updateOnly": true }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Set custom-field values on this member. Each entry is `{ customFieldId, value }` and `value` is always a string — send `\"\"` to clear one. Only on update: an invite rejects it with a 400. Read them back with `?expand=customFields`.", "example": [], "examples": [ [] ], "x-updateOnly": true } }, "additionalProperties": false }, "message": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "4SsY67bC", "examples": [ "4SsY67bC" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "2MuAM0jY", "examples": [ "2MuAM0jY" ] }, "teamId": { "type": "string", "description": "Team this message belongs to. Read-only — resolved from your credentials and from the message's parent context.", "readOnly": true, "example": "cfC83TeS", "examples": [ "cfC83TeS" ] }, "text": { "type": [ "string", "null" ], "description": "Message body, up to 655,350 characters. Supports Markdown formatting, plus embedded mention tags (`<@memberId>` person, `` task, `<#projectId>` project, `` status, `<^listId>` list, `<~labelId>` label, `<$portfolioId>` portfolio, `` discussion). Token glyphs are the literal wire ref format. Nullable for non-text messages.", "example": "Looks good — shipping this today.", "examples": [ "Looks good — shipping this today." ] }, "url": { "type": [ "string", "null" ], "description": "External URL for `type=gif` messages.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "type": { "type": "string", "enum": [ "text", "gif", "document", "audio" ], "description": "Message kind: \"text\" | \"gif\" | \"document\" | \"audio\". Defaults to \"text\" when omitted on create; the non-text kinds require their own payload (url / sharedDocumentId / audioDuration), so only pass an explicit type for those. Fixed at creation — it cannot be changed afterwards.", "example": "text", "examples": [ "text" ] }, "subtype": { "type": [ "string", "null" ], "enum": [ "hello", "joinProject", "joinChat", "createTask", "archiveTask", "unarchiveTask", "addTaskDeadline", "removeTaskDeadline", "completeTask", "moveTask", "moveSubtask", "convertToTask", "untieTask", "tieTask", "assignTask", "unassignTask", "moveProject", "meetingStart", "meetingEnd", "mentionTaskInCommit", "mentionTaskInPR", "addTaskStartDate", "removeTaskStartDate", "sendMessage", "unCompleteTask", "enableRecurringOnTask", "taskAddLabel", "taskRemoveLabel", "taskAddAssignee", "taskRemoveAssignee", "taskAddGoal", "taskRemoveGoal", "taskUpdateDependency", "taskUpdateField", "taskUpdateReminder", "taskUpdateStoryPoints", "timeEntryCreate", "taskOverdue", "taskAddChecklist", "taskRemoveChecklist", "taskUpdateChecklist", "taskAddChecklistItem", "taskRemoveChecklistItem", "taskUpdateChecklistItem", "taskCompleteChecklistItem", "taskUncompleteChecklistItem", "taskAddLabeledAssignee", "taskRemoveLabeledAssignee", "timeEntryEdited", "timeEntryRemoved", "taskAddSubscriber", "taskRemoveSubscriber" ], "description": "Non-null on the system/lifecycle messages the server generates (task assigned, label applied, member joined a chat). Null on messages a person or an agent wrote. Read-only — you cannot create a system message through the API. A few values are not self-explanatory: `hello` is the welcome message posted in a new chat, `tieTask` / `untieTask` record a dependency being added or removed between two tasks, and `moveSubtask` records a subtask being re-parented.", "readOnly": true, "example": "hello", "examples": [ "hello" ] }, "isEdited": { "type": "boolean", "description": "True when the text has been edited at least once. Server-managed by the edit path.", "readOnly": true, "example": false, "examples": [ false ] }, "hideLinkPreview": { "type": "boolean", "description": "When true, link previews are not rendered for URLs in this message.", "example": false, "examples": [ false ] }, "botName": { "type": [ "string", "null" ], "description": "Display name shown for a message mirrored in from a connected app (for example a Slack channel). Null for messages written by a person or an agent. Read-only — set by the mirroring integration, never by an API client.", "readOnly": true, "example": "Example", "examples": [ "Example" ] }, "botAvatar": { "type": [ "string", "null" ], "description": "Avatar URL shown for a message mirrored in from a connected app. Null for messages written by a person or an agent. Read-only — set by the mirroring integration, never by an API client.", "readOnly": true, "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "audioDuration": { "type": [ "number", "null" ], "description": "Audio playback duration in seconds — populated for `type=audio` messages.", "example": 100, "examples": [ 100 ] }, "editHistory": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "format": "date-time" }, "actorId": { "type": "string" }, "source": { "type": "string" } }, "required": [ "id", "timestamp" ], "additionalProperties": true }, "description": "Every edit made to this message, oldest first. Each entry carries `timestamp` and the editor: `id` is the team member who made the edit, or null when an agent or an integration did — in which case `actorId` identifies it. Server-managed.", "readOnly": true, "example": [], "examples": [ [] ] }, "authorId": { "type": [ "string", "null" ], "description": "The team member who wrote this message — a member id, so resolve it with `?expand=author` or `GET /members/{id}`. Null for system and app-mirrored messages — use `createdByActorType` to tell an agent-written message from a human one.", "readOnly": true, "example": "EPmKiCaK", "examples": [ "EPmKiCaK" ] }, "chatId": { "type": [ "string", "null" ], "description": "The chat this message belongs to (group, direct, or a project discussion). Exactly one parent context per message.", "example": "hTIeouEK", "examples": [ "hTIeouEK" ] }, "taskId": { "type": [ "string", "null" ], "description": "The task this message comments on. Exactly one parent context per message.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "documentId": { "type": [ "string", "null" ], "description": "The document this message comments on. Exactly one parent context per message.", "example": "ELe0nkum", "examples": [ "ELe0nkum" ] }, "fileId": { "type": [ "string", "null" ], "description": "The file this message comments on. Exactly one parent context per message — `fileId` and `annotationId` may be sent together (a comment on an annotation drawn on a file).", "example": "xvM2toUM", "examples": [ "xvM2toUM" ] }, "annotationId": { "type": [ "string", "null" ], "description": "The annotation this message is threaded under. Exactly one parent context per message — `fileId` and `annotationId` may be sent together (a comment on an annotation drawn on a file).", "example": "863BiyIc", "examples": [ "863BiyIc" ] }, "parentMessageId": { "type": [ "string", "null" ], "description": "The message this one replies to. Exactly one parent context per message.", "example": "gx21BskY", "examples": [ "gx21BskY" ] }, "sharedDocumentId": { "type": [ "string", "null" ], "description": "A document shared into a chat message. Distinct from `documentId`, which marks a comment ON a document. Read-only — share a document from the Nifty app.", "readOnly": true, "example": "vjciEwQy", "examples": [ "vjciEwQy" ] }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "glyph": { "type": "string" }, "type": { "type": "string", "enum": [ "member" ] }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "glyph", "type", "id", "name" ], "additionalProperties": false }, "description": "Resolved mentions found in `text`, as a read-only sidecar: each entry is { glyph (the raw `<@id>` token, still present in `text`), type (what the mention refers to — only `member` today), id, name (the display name, or null if the referenced member is deleted or not visible to you) }. Read `text` for the message; read `mentions` to show WHO is referenced without losing the ids. Absent when `text` has no mentions. Server-computed.", "readOnly": true, "example": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "examples": [ [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ] ] }, "repliesCount": { "type": "integer", "minimum": 0, "description": "How many replies this message has in its thread — 0 when it has none. Named `repliesCount` because `replies` is the expandable thread relation on this resource. Server-computed. ⚠️ A reply hidden from your ROLE is excluded from `?expand=replies` but is still counted here, so this can exceed the length of the array you receive.", "readOnly": true, "example": 3, "examples": [ 3 ] }, "repliers": { "type": "array", "items": { "type": "string" }, "description": "The distinct TeamMembers who replied in this message's thread, as ids — `[]` when there is no thread. TeamMember shortids, NOT actor UUIDs: resolve one with `GET /members/{id}`. Server-computed, and carries the same role-redaction caveat as `repliesCount`.", "readOnly": true, "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ] } }, "required": [ "id", "createdAt", "teamId", "type" ], "additionalProperties": true }, "messageExpanded": { "description": "A Message with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/message" }, { "type": "object", "properties": { "author": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=author`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "chat": { "allOf": [ { "$ref": "#/components/schemas/chat" } ], "description": "The related Chat, present only when you pass `?expand=chat`.", "x-example-omit": true }, "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "document": { "allOf": [ { "$ref": "#/components/schemas/document" } ], "description": "The related Document, present only when you pass `?expand=document`.", "x-example-omit": true }, "file": { "allOf": [ { "$ref": "#/components/schemas/file" } ], "description": "The related File, present only when you pass `?expand=file`.", "x-example-omit": true }, "annotation": { "allOf": [ { "$ref": "#/components/schemas/annotation" } ], "description": "The related Annotation, present only when you pass `?expand=annotation`.", "x-example-omit": true }, "parentMessage": { "allOf": [ { "$ref": "#/components/schemas/message" } ], "description": "The related Message, present only when you pass `?expand=parentMessage`.", "x-example-omit": true }, "sharedDocument": { "allOf": [ { "$ref": "#/components/schemas/document" } ], "description": "The related Document, present only when you pass `?expand=sharedDocument`.", "x-example-omit": true }, "tagged": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=tagged`.", "x-example-omit": true }, "seenBy": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=seenBy`.", "x-example-omit": true }, "hiddenFor": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The linked Role rows, present only when you pass `?expand=hiddenFor`.", "x-example-omit": true }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/file" }, "description": "The linked File rows, present only when you pass `?expand=files`.", "x-example-omit": true }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/message" }, "description": "The linked Message rows, present only when you pass `?expand=replies`.", "x-example-omit": true } } } ] }, "messageCreated": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "4SsY67bC", "examples": [ "4SsY67bC" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "2MuAM0jY", "examples": [ "2MuAM0jY" ] }, "teamId": { "type": "string", "description": "Team this message belongs to. Read-only — resolved from your credentials and from the message's parent context.", "readOnly": true, "example": "cfC83TeS", "examples": [ "cfC83TeS" ] }, "text": { "type": [ "string", "null" ], "description": "Message body, up to 655,350 characters. Supports Markdown formatting, plus embedded mention tags (`<@memberId>` person, `` task, `<#projectId>` project, `` status, `<^listId>` list, `<~labelId>` label, `<$portfolioId>` portfolio, `` discussion). Token glyphs are the literal wire ref format. Nullable for non-text messages.", "example": "Looks good — shipping this today.", "examples": [ "Looks good — shipping this today." ] }, "url": { "type": [ "string", "null" ], "description": "External URL for `type=gif` messages.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "type": { "type": "string", "enum": [ "text", "gif", "document", "audio" ], "description": "Message kind: \"text\" | \"gif\" | \"document\" | \"audio\". Defaults to \"text\" when omitted on create; the non-text kinds require their own payload (url / sharedDocumentId / audioDuration), so only pass an explicit type for those. Fixed at creation — it cannot be changed afterwards.", "example": "text", "examples": [ "text" ] }, "subtype": { "type": [ "string", "null" ], "enum": [ "hello", "joinProject", "joinChat", "createTask", "archiveTask", "unarchiveTask", "addTaskDeadline", "removeTaskDeadline", "completeTask", "moveTask", "moveSubtask", "convertToTask", "untieTask", "tieTask", "assignTask", "unassignTask", "moveProject", "meetingStart", "meetingEnd", "mentionTaskInCommit", "mentionTaskInPR", "addTaskStartDate", "removeTaskStartDate", "sendMessage", "unCompleteTask", "enableRecurringOnTask", "taskAddLabel", "taskRemoveLabel", "taskAddAssignee", "taskRemoveAssignee", "taskAddGoal", "taskRemoveGoal", "taskUpdateDependency", "taskUpdateField", "taskUpdateReminder", "taskUpdateStoryPoints", "timeEntryCreate", "taskOverdue", "taskAddChecklist", "taskRemoveChecklist", "taskUpdateChecklist", "taskAddChecklistItem", "taskRemoveChecklistItem", "taskUpdateChecklistItem", "taskCompleteChecklistItem", "taskUncompleteChecklistItem", "taskAddLabeledAssignee", "taskRemoveLabeledAssignee", "timeEntryEdited", "timeEntryRemoved", "taskAddSubscriber", "taskRemoveSubscriber" ], "description": "Non-null on the system/lifecycle messages the server generates (task assigned, label applied, member joined a chat). Null on messages a person or an agent wrote. Read-only — you cannot create a system message through the API. A few values are not self-explanatory: `hello` is the welcome message posted in a new chat, `tieTask` / `untieTask` record a dependency being added or removed between two tasks, and `moveSubtask` records a subtask being re-parented.", "readOnly": true, "example": "hello", "examples": [ "hello" ] }, "isEdited": { "type": "boolean", "description": "True when the text has been edited at least once. Server-managed by the edit path.", "readOnly": true, "example": false, "examples": [ false ] }, "hideLinkPreview": { "type": "boolean", "description": "When true, link previews are not rendered for URLs in this message.", "example": false, "examples": [ false ] }, "botName": { "type": [ "string", "null" ], "description": "Display name shown for a message mirrored in from a connected app (for example a Slack channel). Null for messages written by a person or an agent. Read-only — set by the mirroring integration, never by an API client.", "readOnly": true, "example": "Example", "examples": [ "Example" ] }, "botAvatar": { "type": [ "string", "null" ], "description": "Avatar URL shown for a message mirrored in from a connected app. Null for messages written by a person or an agent. Read-only — set by the mirroring integration, never by an API client.", "readOnly": true, "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "audioDuration": { "type": [ "number", "null" ], "description": "Audio playback duration in seconds — populated for `type=audio` messages.", "example": 100, "examples": [ 100 ] }, "editHistory": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "format": "date-time" }, "actorId": { "type": "string" }, "source": { "type": "string" } }, "required": [ "id", "timestamp" ], "additionalProperties": true }, "description": "Every edit made to this message, oldest first. Each entry carries `timestamp` and the editor: `id` is the team member who made the edit, or null when an agent or an integration did — in which case `actorId` identifies it. Server-managed.", "readOnly": true, "example": [], "examples": [ [] ] }, "authorId": { "type": [ "string", "null" ], "description": "The team member who wrote this message — a member id, so resolve it with `?expand=author` or `GET /members/{id}`. Null for system and app-mirrored messages — use `createdByActorType` to tell an agent-written message from a human one.", "readOnly": true, "example": "EPmKiCaK", "examples": [ "EPmKiCaK" ] }, "chatId": { "type": [ "string", "null" ], "description": "The chat this message belongs to (group, direct, or a project discussion). Exactly one parent context per message.", "example": "hTIeouEK", "examples": [ "hTIeouEK" ] }, "taskId": { "type": [ "string", "null" ], "description": "The task this message comments on. Exactly one parent context per message.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "documentId": { "type": [ "string", "null" ], "description": "The document this message comments on. Exactly one parent context per message.", "example": "ELe0nkum", "examples": [ "ELe0nkum" ] }, "fileId": { "type": [ "string", "null" ], "description": "The file this message comments on. Exactly one parent context per message — `fileId` and `annotationId` may be sent together (a comment on an annotation drawn on a file).", "example": "xvM2toUM", "examples": [ "xvM2toUM" ] }, "annotationId": { "type": [ "string", "null" ], "description": "The annotation this message is threaded under. Exactly one parent context per message — `fileId` and `annotationId` may be sent together (a comment on an annotation drawn on a file).", "example": "863BiyIc", "examples": [ "863BiyIc" ] }, "parentMessageId": { "type": [ "string", "null" ], "description": "The message this one replies to. Exactly one parent context per message.", "example": "gx21BskY", "examples": [ "gx21BskY" ] }, "sharedDocumentId": { "type": [ "string", "null" ], "description": "A document shared into a chat message. Distinct from `documentId`, which marks a comment ON a document. Read-only — share a document from the Nifty app.", "readOnly": true, "example": "vjciEwQy", "examples": [ "vjciEwQy" ] }, "mentions": { "type": "array", "items": { "type": "object", "properties": { "glyph": { "type": "string" }, "type": { "type": "string", "enum": [ "member" ] }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "glyph", "type", "id", "name" ], "additionalProperties": false }, "description": "Resolved mentions found in `text`, as a read-only sidecar: each entry is { glyph (the raw `<@id>` token, still present in `text`), type (what the mention refers to — only `member` today), id, name (the display name, or null if the referenced member is deleted or not visible to you) }. Read `text` for the message; read `mentions` to show WHO is referenced without losing the ids. Absent when `text` has no mentions. Server-computed.", "readOnly": true, "example": [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ], "examples": [ [ { "glyph": "<@P3hYIKqK>", "type": "member", "id": "P3hYIKqK", "name": "Ada Lovelace" } ] ] }, "repliesCount": { "type": "integer", "minimum": 0, "description": "How many replies this message has in its thread — 0 when it has none. Named `repliesCount` because `replies` is the expandable thread relation on this resource. Server-computed. ⚠️ A reply hidden from your ROLE is excluded from `?expand=replies` but is still counted here, so this can exceed the length of the array you receive.", "readOnly": true, "example": 3, "examples": [ 3 ] }, "repliers": { "type": "array", "items": { "type": "string" }, "description": "The distinct TeamMembers who replied in this message's thread, as ids — `[]` when there is no thread. TeamMember shortids, NOT actor UUIDs: resolve one with `GET /members/{id}`. Server-computed, and carries the same role-redaction caveat as `repliesCount`.", "readOnly": true, "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ] }, "created": { "type": "boolean", "description": "DM idempotency signal (create-response only): true if recipientMemberId minted a new direct chat, false if an existing 1:1 was reused. Absent for non-DM creates.", "readOnly": true, "example": false, "examples": [ false ] } }, "required": [ "id", "createdAt", "teamId", "type" ], "additionalProperties": true }, "messageCreate": { "type": "object", "properties": { "text": { "type": [ "string", "null" ], "maxLength": 655350, "description": "Message body. Supports Markdown formatting, plus embedded mention tags (`<@memberId>` person, `` task, `<#projectId>` project, `` status, `<^listId>` list, `<~labelId>` label, `<$portfolioId>` portfolio, `` discussion). Nullable for non-text messages (gif, audio).", "example": "Looks good — shipping this today.", "examples": [ "Looks good — shipping this today." ] }, "url": { "type": [ "string", "null" ], "description": "External URL — used for `type=gif` messages (GIF source URL). Null otherwise.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ], "x-createOnly": true }, "type": { "type": "string", "enum": [ "text", "gif", "document", "audio" ], "default": "text", "description": "Message kind: \"text\" | \"gif\" | \"document\" | \"audio\". Defaults to \"text\" when omitted on create; the non-text kinds require their own payload (url / sharedDocumentId / audioDuration), so only pass an explicit type for those. Fixed at creation — it cannot be changed afterwards.", "example": "text", "examples": [ "text" ], "x-createOnly": true }, "hideLinkPreview": { "type": "boolean", "description": "When true, link previews are not rendered for URLs in this message.", "example": false, "examples": [ false ] }, "audioDuration": { "type": [ "number", "null" ], "description": "Audio playback duration in seconds — populated for `type=audio` messages.", "example": 100, "examples": [ 100 ], "x-createOnly": true }, "chatId": { "type": [ "string", "null" ], "description": "The chat this message belongs to (group, direct, or a project discussion). Exactly one parent context per message.", "example": "hTIeouEK", "examples": [ "hTIeouEK" ], "x-createOnly": true }, "taskId": { "type": [ "string", "null" ], "description": "The task this message comments on. Exactly one parent context per message.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ], "x-createOnly": true }, "documentId": { "type": [ "string", "null" ], "description": "The document this message comments on. Exactly one parent context per message.", "example": "ELe0nkum", "examples": [ "ELe0nkum" ], "x-createOnly": true }, "fileId": { "type": [ "string", "null" ], "description": "The file this message comments on. Exactly one parent context per message — `fileId` and `annotationId` may be sent together (a comment on an annotation drawn on a file).", "example": "xvM2toUM", "examples": [ "xvM2toUM" ], "x-createOnly": true }, "annotationId": { "type": [ "string", "null" ], "description": "The annotation this message is threaded under. Exactly one parent context per message — `fileId` and `annotationId` may be sent together (a comment on an annotation drawn on a file).", "example": "863BiyIc", "examples": [ "863BiyIc" ], "x-createOnly": true }, "parentMessageId": { "type": [ "string", "null" ], "description": "The message this one replies to. Exactly one parent context per message.", "example": "gx21BskY", "examples": [ "gx21BskY" ], "x-createOnly": true }, "recipientMemberId": { "type": "string", "minLength": 1, "description": "Send a direct message: provide this instead of `chatId`, `taskId` or the other parent contexts. The 1:1 chat is created if it does not exist. Create-only, and must differ from the caller.", "example": "AdeWqOs6", "examples": [ "AdeWqOs6" ], "x-createOnly": true }, "tagged": { "type": "array", "items": { "type": "string" }, "description": "Team members to @-mention on this message, by id. Accepted when the message is created; the mention list of an existing message is not editable, so it is not part of the update body. Read them back with `?expand=tagged`.", "example": [ "lnQ0jGkG" ], "examples": [ [ "lnQ0jGkG" ] ], "x-createOnly": true }, "files": { "type": "array", "items": { "type": "string" }, "description": "Existing files attached to this message, by id. Writable on create and on update: on update the array you send becomes the COMPLETE set, so a file dropped from it is detached (the file itself is not deleted). Omit the key to leave it untouched. Read them back with `?expand=files`.", "example": [ "xvM2toUM" ], "examples": [ [ "xvM2toUM" ] ] } }, "additionalProperties": false, "oneOf": [ { "required": [ "chatId" ] }, { "required": [ "taskId" ] }, { "required": [ "documentId" ] }, { "required": [ "fileId" ] }, { "required": [ "annotationId" ] }, { "required": [ "parentMessageId" ] }, { "required": [ "recipientMemberId" ] } ] }, "messageUpdate": { "type": "object", "properties": { "text": { "type": [ "string", "null" ], "maxLength": 655350, "description": "Message body. Supports Markdown formatting, plus embedded mention tags (`<@memberId>` person, `` task, `<#projectId>` project, `` status, `<^listId>` list, `<~labelId>` label, `<$portfolioId>` portfolio, `` discussion). Nullable for non-text messages (gif, audio).", "example": "Looks good — shipping this today.", "examples": [ "Looks good — shipping this today." ] }, "hideLinkPreview": { "type": "boolean", "description": "When true, link previews are not rendered for URLs in this message.", "example": false, "examples": [ false ] }, "files": { "type": "array", "items": { "type": "string" }, "description": "Existing files attached to this message, by id. Writable on create and on update: on update the array you send becomes the COMPLETE set, so a file dropped from it is detached (the file itself is not deleted). Omit the key to leave it untouched. Read them back with `?expand=files`.", "example": [ "xvM2toUM" ], "examples": [ [ "xvM2toUM" ] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "portfolio": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "1YEYsy2X", "examples": [ "1YEYsy2X" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "RzEGIS2T", "examples": [ "RzEGIS2T" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "icon": { "type": [ "string", "null" ], "description": "Icon image URL for the portfolio.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": "string", "maxLength": 3, "description": "Up to 3 characters shown when the portfolio has no icon. Derived from `name` when omitted on create.", "example": "NB", "examples": [ "NB" ] }, "color": { "type": "string", "description": "Primary brand colour as a 6-digit hex value, e.g. `#00A99B`. Assigned from the Nifty palette when omitted on create.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "secondaryColor": { "type": "string", "description": "Secondary brand colour as a 6-digit hex value. Derived from `color`; values sent by a client are ignored.", "example": "#0E7C74", "examples": [ "#0E7C74" ] }, "isGeneral": { "type": "boolean", "description": "True for the team's General portfolio. Every team has exactly one: projects created without a `portfolioId` land there, and it cannot be deleted.", "readOnly": true, "example": false, "examples": [ false ] }, "order": { "type": [ "number", "null" ], "description": "Sort order of this portfolio within the team. Auto-assigned on create; send a new value to reorder.", "example": 2000, "examples": [ 2000 ] }, "ownerId": { "type": [ "string", "null" ], "description": "Team member designated as the portfolio owner. Set with PATCH — on create the owner is always the caller (or the team owner for a non-member caller), so it is not part of the create body.", "example": "QpCuKyI2", "examples": [ "QpCuKyI2" ] } }, "required": [ "id", "createdAt", "name", "initials", "color", "secondaryColor", "isGeneral" ], "additionalProperties": true }, "portfolioExpanded": { "description": "A Portfolio with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/portfolio" }, { "type": "object", "properties": { "owner": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=owner`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=members`.", "x-example-omit": true } } } ] }, "portfolioCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "icon": { "type": [ "string", "null" ], "description": "Icon image URL for the portfolio.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": "string", "maxLength": 3, "description": "Up to 3 characters shown when the portfolio has no icon. Derived from `name` when omitted on create.", "example": "NB", "examples": [ "NB" ] }, "color": { "type": "string", "description": "Primary brand colour as a 6-digit hex value, e.g. `#00A99B`. Assigned from the Nifty palette when omitted on create.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order of this portfolio within the team. Auto-assigned on create; send a new value to reorder.", "example": 2000, "examples": [ 2000 ] }, "members": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team member ids belonging to this portfolio. Send `members` in the create or update body to REPLACE the whole roster; use `POST` / `DELETE /portfolios/{id}/members` to add or remove individuals without touching the rest. Read the materialized rows with `?expand=members`.", "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ] } }, "required": [ "name" ], "additionalProperties": false }, "portfolioUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "icon": { "type": [ "string", "null" ], "description": "Icon image URL for the portfolio.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": "string", "maxLength": 3, "description": "Up to 3 characters shown when the portfolio has no icon. Derived from `name` when omitted on create.", "example": "NB", "examples": [ "NB" ] }, "color": { "type": "string", "description": "Primary brand colour as a 6-digit hex value, e.g. `#00A99B`. Assigned from the Nifty palette when omitted on create.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "ownerId": { "type": "string", "minLength": 1, "description": "Team member designated as the portfolio owner. Set with PATCH — on create the owner is always the caller (or the team owner for a non-member caller), so it is not part of the create body.", "example": "QpCuKyI2", "examples": [ "QpCuKyI2" ], "x-updateOnly": true }, "order": { "type": [ "number", "null" ], "description": "Sort order of this portfolio within the team. Auto-assigned on create; send a new value to reorder.", "example": 2000, "examples": [ 2000 ] }, "members": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team member ids belonging to this portfolio. Send `members` in the create or update body to REPLACE the whole roster; use `POST` / `DELETE /portfolios/{id}/members` to add or remove individuals without touching the rest. Read the materialized rows with `?expand=members`.", "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "presenceStatus": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "WjkiuqmY", "examples": [ "WjkiuqmY" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "description": "Name of the status, shown to the team.", "example": "Example", "examples": [ "Example" ] }, "emoji": { "type": [ "string", "null" ], "description": "A single emoji shown beside the status.", "example": ":rocket:", "examples": [ ":rocket:" ] }, "appearsOnline": { "type": "boolean", "description": "Whether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.", "example": false, "examples": [ false ] }, "muteNotifications": { "type": "boolean", "description": "Whether the member's notifications are silenced while this status is active.", "example": false, "examples": [ false ] }, "defaultDurationMs": { "type": [ "number", "null" ], "description": "How long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.", "example": 3600000, "examples": [ 3600000 ] }, "isDefault": { "type": "boolean", "description": "True for the templates Nifty seeds into every workspace. Server-managed: you cannot promote or demote a template through the API.", "readOnly": true, "example": false, "examples": [ false ] } }, "required": [ "id", "createdAt", "name", "appearsOnline", "muteNotifications", "isDefault" ], "additionalProperties": true }, "presenceStatusExpanded": { "description": "A Presence Status with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/presenceStatus" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true } } } ] }, "presenceStatusCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the status, shown to the team.", "example": "Example", "examples": [ "Example" ] }, "appearsOnline": { "type": "boolean", "description": "Whether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.", "example": false, "examples": [ false ] }, "emoji": { "type": [ "string", "null" ], "maxLength": 8, "description": "A single emoji shown beside the status.", "example": ":rocket:", "examples": [ ":rocket:" ] }, "muteNotifications": { "type": "boolean", "description": "Whether the member's notifications are silenced while this status is active.", "example": false, "examples": [ false ] }, "defaultDurationMs": { "type": [ "number", "null" ], "description": "How long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.", "example": 3600000, "examples": [ 3600000 ] } }, "required": [ "name", "appearsOnline" ], "additionalProperties": false }, "presenceStatusUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the status, shown to the team.", "example": "Example", "examples": [ "Example" ] }, "appearsOnline": { "type": "boolean", "description": "Whether the member is shown as online to their team while this status is active. This is an intent you set, not a live presence reading.", "example": false, "examples": [ false ] }, "emoji": { "type": [ "string", "null" ], "maxLength": 8, "description": "A single emoji shown beside the status.", "example": ":rocket:", "examples": [ ":rocket:" ] }, "muteNotifications": { "type": "boolean", "description": "Whether the member's notifications are silenced while this status is active.", "example": false, "examples": [ false ] }, "defaultDurationMs": { "type": [ "number", "null" ], "description": "How long the status stays on before it expires by itself, in milliseconds — 3600000 is one hour. Omit it (or send null) for a status that never auto-expires.", "example": 3600000, "examples": [ 3600000 ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Member who soft-deleted this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "Enmkg49J", "examples": [ "Enmkg49J" ] }, "archived": { "type": "boolean", "description": "Archived projects are hidden from default project lists. Archiving does NOT cascade — tasks and lists inside the project stay active. Set it with PATCH; a project cannot be created already archived.", "example": false, "examples": [ false ] }, "niceId": { "type": [ "string", "null" ], "description": "Short project key used in task references — a project with the key `PRJ` has tasks that read `PRJ-14`. Server-generated.", "readOnly": true, "example": "PRJ", "examples": [ "PRJ" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name. Must be unique among the projects in the same portfolio. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional project description. Supports Markdown formatting.", "example": "A concise description.", "examples": [ "A concise description." ] }, "icon": { "type": [ "string", "null" ], "description": "Icon image URL for the project. Objects use `icon`; people use `avatar`.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": "string", "maxLength": 3, "description": "Up to 3 characters shown when the project has no icon. Derived from `name` when omitted.", "example": "NB", "examples": [ "NB" ] }, "color": { "type": "string", "description": "Primary brand colour as a 6-digit hex value, e.g. `#00A99B`. Assigned from the Nifty palette when omitted.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "secondaryColor": { "type": "string", "description": "Secondary brand colour as a 6-digit hex value. Derived from `color` when omitted.", "example": "#0E7C74", "examples": [ "#0E7C74" ] }, "portfolioId": { "type": [ "string", "null" ], "description": "The portfolio this project is grouped under. Defaults to the team's General portfolio when omitted on create. Immutable after create.", "example": "1YEYsy2X", "examples": [ "1YEYsy2X" ] }, "accessType": { "type": "string", "enum": [ "public", "limited" ], "description": "Visibility: `limited` (default — members only) or `public` (team-wide; all team members are added automatically). A project has exactly these two levels.", "example": "public", "examples": [ "public" ] }, "modules": { "type": "array", "items": { "type": "string", "enum": [ "home", "milestones", "tasks", "discussion", "documents", "files", "forms", "calendar" ] }, "description": "Feature tabs the project exposes. SELECT only the ones this project needs — OMITTING the field enables ALL 8, which clutters a focused project. Options: `tasks` (the task board), `milestones` (dated roadmap of lists), `calendar` (calendar of dated items), `documents` (collaborative docs), `files` (file storage), `discussion` (threaded project discussions), `forms` (intake/survey forms), `home` (project overview). e.g. a content calendar → [tasks, calendar, files]; a bug tracker → [tasks]; a knowledge base → [documents, files]. Set once at create; immutable afterwards.", "example": [ "home" ], "examples": [ [ "home" ] ] }, "defaultTasksView": { "type": "string", "enum": [ "table", "calendar", "swimlane", "kanban", "timeline", "report" ], "description": "Default task board view: `table`, `calendar`, `swimlane`, `kanban`, `timeline` or `report`.", "example": "table", "examples": [ "table" ] }, "hiddenListColumns": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Columns hidden on the list view. Each entry is either a built-in column key (`name`, `assignee`, `dueDate`, `status`, `list`, `labels`, `estimate`) or the id of a custom field attached to the project.", "example": [ "estimate", "labels" ], "examples": [ [ "estimate", "labels" ] ] }, "listColumnsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List-view columns in display order, using the same vocabulary as `hiddenListColumns` — built-in column keys and/or attached custom-field ids.", "example": [ "name", "assignee", "dueDate" ], "examples": [ [ "name", "assignee", "dueDate" ] ] }, "customFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Project-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "taskCustomFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Task-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "listCustomFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "autoMilestones": { "type": "boolean", "description": "When true, monthly lists are created automatically for this project. Applied at create time.", "example": false, "examples": [ false ] }, "hideUsersFromGuests": { "type": "boolean", "description": "Hide member list from guest role", "example": false, "examples": [ false ] }, "subtaskStatusEnabled": { "type": "boolean", "description": "Enable per-subtask status tracking", "example": false, "examples": [ false ] }, "queryAllFiles": { "type": "boolean", "description": "Query files across all tasks", "example": false, "examples": [ false ] }, "projectFolderId": { "type": [ "string", "null" ], "description": "The project folder this project is filed under, within its portfolio. null = unfiled.", "example": "0sSAIGwG", "examples": [ "0sSAIGwG" ] }, "ownerId": { "type": [ "string", "null" ], "description": "The team member who owns this project. Change it with the project `transfer` operation — it is not settable on create or update. Null only while a project has no owner (a workspace-imported project, or one whose owner has been removed from the team).", "readOnly": true, "example": "QpCuKyI2", "examples": [ "QpCuKyI2" ] }, "discussionChatId": { "type": [ "string", "null" ], "description": "Id of the project's discussion chat, or null if it has none. Fetch its messages with `GET /messages?chatId=`. Reading those messages requires chat membership — access to the project alone is not enough. Discussion-chat messages only: this is NOT a union of the project's task, document and file comments.", "readOnly": true, "example": "lNAaW0F4", "examples": [ "lNAaW0F4" ] }, "defaultStatusId": { "type": [ "string", "null" ], "description": "The project's first status column, where a new task lands by default. Pass it as `statusId` when creating a task — a task with no status is invisible on the board. null until the project has a status. Not returned on create/update responses; read it with `GET /projects/{id}`.", "readOnly": true, "example": "O9nWOgic", "examples": [ "O9nWOgic" ] } }, "required": [ "id", "createdAt", "name", "initials", "color", "secondaryColor", "accessType", "modules", "autoMilestones", "hideUsersFromGuests", "subtaskStatusEnabled", "queryAllFiles" ], "additionalProperties": true }, "projectExpanded": { "description": "A Project with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/project" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "deletedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=deletedBy`.", "x-example-omit": true }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=members`.", "x-example-omit": true }, "portfolio": { "allOf": [ { "$ref": "#/components/schemas/portfolio" } ], "description": "The related Portfolio, present only when you pass `?expand=portfolio`.", "x-example-omit": true }, "discussionChat": { "type": "array", "items": { "$ref": "#/components/schemas/chat" }, "description": "The linked Chat rows, present only when you pass `?expand=discussionChat`.", "x-example-omit": true }, "customFields": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The linked attachedCustomField rows, present only when you pass `?expand=customFields`.", "x-example-omit": true } } } ] }, "projectCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name. Must be unique among the projects in the same portfolio. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional project description. Supports Markdown formatting.", "example": "A concise description.", "examples": [ "A concise description." ] }, "icon": { "type": [ "string", "null" ], "description": "Icon image URL for the project. Objects use `icon`; people use `avatar`.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": "string", "maxLength": 3, "description": "Up to 3 characters shown when the project has no icon. Derived from `name` when omitted.", "example": "NB", "examples": [ "NB" ] }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Primary brand colour as a 6-digit hex value, e.g. `#00A99B`. Assigned from the Nifty palette when omitted.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "secondaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Secondary brand colour as a 6-digit hex value. Derived from `color` when omitted.", "example": "#0E7C74", "examples": [ "#0E7C74" ] }, "portfolioId": { "type": [ "string", "null" ], "description": "The portfolio this project is grouped under. Defaults to the team's General portfolio when omitted on create. Immutable after create.", "example": "1YEYsy2X", "examples": [ "1YEYsy2X" ], "x-createOnly": true }, "accessType": { "type": "string", "enum": [ "public", "limited" ], "description": "Visibility: limited (default — only invited members) or public (all team members auto-added). Omit for limited; pass public explicitly to make the project team-wide.", "example": "public", "examples": [ "public" ] }, "modules": { "type": "array", "items": { "type": "string", "enum": [ "home", "milestones", "tasks", "discussion", "documents", "files", "forms", "calendar" ] }, "description": "Feature tabs the project exposes. Omitting the field enables all eight. Options: `tasks` (the task board), `milestones` (dated roadmap of lists), `calendar` (calendar of dated items), `documents` (collaborative docs), `files` (file storage), `discussion` (threaded project discussions), `forms` (intake/survey forms), `home` (project overview). e.g. a content calendar → [tasks, calendar, files]; a bug tracker → [tasks]; a knowledge base → [documents, files]; a client project → [tasks, milestones, files, discussion].", "example": [ "home" ], "examples": [ [ "home" ] ], "x-createOnly": true }, "defaultTasksView": { "type": "string", "enum": [ "table", "calendar", "swimlane", "kanban", "timeline", "report" ], "description": "Default task board view: table | calendar | swimlane | kanban | timeline | report.", "example": "table", "examples": [ "table" ] }, "hiddenListColumns": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Columns hidden on the list view. Each entry is either a built-in column key (`name`, `assignee`, `dueDate`, `status`, `list`, `labels`, `estimate`) or the id of a custom field attached to the project.", "example": [ "estimate", "labels" ], "examples": [ [ "estimate", "labels" ] ] }, "listColumnsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List-view columns in display order, using the same vocabulary as `hiddenListColumns` — built-in column keys and/or attached custom-field ids.", "example": [ "name", "assignee", "dueDate" ], "examples": [ [ "name", "assignee", "dueDate" ] ] }, "customFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Project-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "taskCustomFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Task-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "listCustomFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "autoMilestones": { "type": "boolean", "description": "When true, monthly lists are created automatically for this project. Applied at create time.", "example": false, "examples": [ false ] }, "hideUsersFromGuests": { "type": "boolean", "description": "Hide member list from guest role", "example": false, "examples": [ false ] }, "subtaskStatusEnabled": { "type": "boolean", "description": "Enable per-subtask status tracking", "example": false, "examples": [ false ] }, "queryAllFiles": { "type": "boolean", "description": "Query files across all tasks", "example": false, "examples": [ false ] }, "members": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team member ids on this project. REPLACE semantics — the array you send in the create or update body becomes the complete roster: ids you omit are removed, ids you add are invited. Omit the key to leave the roster untouched. Read the materialized rows with `?expand=members`.", "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ] }, "projectFolderId": { "type": [ "string", "null" ], "description": "The project folder this project is filed under, within its portfolio. null = unfiled.", "example": "0sSAIGwG", "examples": [ "0sSAIGwG" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Custom-field values on this project. READ: `?expand=customFields` returns the values attached to this project. WRITE: include `customFields: [{ customFieldId, value }]` in the create/update body to set values — each one is checked against its field definition before the write commits (value is always a string; max 50 entries per request; `\"\"` clears). Field definitions live on the read-only `customField` resource.", "example": [], "examples": [ [] ] } }, "required": [ "name" ], "additionalProperties": false }, "projectUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name. Must be unique among the projects in the same portfolio. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Optional project description. Supports Markdown formatting.", "example": "A concise description.", "examples": [ "A concise description." ] }, "icon": { "type": [ "string", "null" ], "description": "Icon image URL for the project. Objects use `icon`; people use `avatar`.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "initials": { "type": "string", "maxLength": 3, "description": "Up to 3 characters shown when the project has no icon. Derived from `name` when omitted.", "example": "NB", "examples": [ "NB" ] }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Primary brand colour as a 6-digit hex value, e.g. `#00A99B`. Assigned from the Nifty palette when omitted.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "secondaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Secondary brand colour as a 6-digit hex value. Derived from `color` when omitted.", "example": "#0E7C74", "examples": [ "#0E7C74" ] }, "archived": { "type": "boolean", "description": "Archived projects are hidden from default project lists. Archiving does NOT cascade — tasks and lists inside the project stay active. Set it with PATCH; a project cannot be created already archived.", "example": false, "examples": [ false ], "x-updateOnly": true }, "accessType": { "type": "string", "enum": [ "public", "limited" ], "description": "Visibility: limited (default — only invited members) or public (all team members auto-added). Omit for limited; pass public explicitly to make the project team-wide.", "example": "public", "examples": [ "public" ] }, "defaultTasksView": { "type": "string", "enum": [ "table", "calendar", "swimlane", "kanban", "timeline", "report" ], "description": "Default task board view: table | calendar | swimlane | kanban | timeline | report.", "example": "table", "examples": [ "table" ] }, "hiddenListColumns": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Columns hidden on the list view. Each entry is either a built-in column key (`name`, `assignee`, `dueDate`, `status`, `list`, `labels`, `estimate`) or the id of a custom field attached to the project.", "example": [ "estimate", "labels" ], "examples": [ [ "estimate", "labels" ] ] }, "listColumnsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List-view columns in display order, using the same vocabulary as `hiddenListColumns` — built-in column keys and/or attached custom-field ids.", "example": [ "name", "assignee", "dueDate" ], "examples": [ [ "name", "assignee", "dueDate" ] ] }, "customFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Project-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "taskCustomFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Task-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "listCustomFieldsOrder": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "List-level custom-field ids in display order.", "example": [ "cf_6GWCcskG", "cf_qHsUISQS" ], "examples": [ [ "cf_6GWCcskG", "cf_qHsUISQS" ] ] }, "autoMilestones": { "type": "boolean", "description": "When true, monthly lists are created automatically for this project. Applied at create time.", "example": false, "examples": [ false ] }, "hideUsersFromGuests": { "type": "boolean", "description": "Hide member list from guest role", "example": false, "examples": [ false ] }, "subtaskStatusEnabled": { "type": "boolean", "description": "Enable per-subtask status tracking", "example": false, "examples": [ false ] }, "queryAllFiles": { "type": "boolean", "description": "Query files across all tasks", "example": false, "examples": [ false ] }, "members": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Team member ids on this project. REPLACE semantics — the array you send in the create or update body becomes the complete roster: ids you omit are removed, ids you add are invited. Omit the key to leave the roster untouched. Read the materialized rows with `?expand=members`.", "example": [ "P3hYIKqK" ], "examples": [ [ "P3hYIKqK" ] ] }, "projectFolderId": { "type": [ "string", "null" ], "description": "The project folder this project is filed under, within its portfolio. null = unfiled.", "example": "0sSAIGwG", "examples": [ "0sSAIGwG" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Custom-field values on this project. READ: `?expand=customFields` returns the values attached to this project. WRITE: include `customFields: [{ customFieldId, value }]` in the create/update body to set values — each one is checked against its field definition before the write commits (value is always a string; max 50 entries per request; `\"\"` clears). Field definitions live on the read-only `customField` resource.", "example": [], "examples": [ [] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "projectActivity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "Nl0Hmwsa", "examples": [ "Nl0Hmwsa" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event happened.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "projectId": { "type": "string", "minLength": 1, "description": "The project this activity belongs to.", "readOnly": true, "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "type": { "type": "string", "enum": [ "projectCreated", "usersJoined", "usersLeft", "listCreated", "listMilestoneCreated", "listUnlocked", "taskCompleted", "fileUploaded", "docCreated" ], "description": "What happened: `projectCreated`, `usersJoined`, `usersLeft`, `listCreated`, `listMilestoneCreated`, `listUnlocked`, `taskCompleted`, `fileUploaded` or `docCreated`. This value determines which of the reference ids below is set.", "readOnly": true, "example": "taskCompleted", "examples": [ "taskCompleted" ] }, "taskId": { "type": [ "string", "null" ], "description": "The task this activity references. Set for `taskCompleted`; null otherwise.", "readOnly": true, "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "listId": { "type": [ "string", "null" ], "description": "The list this activity references. Set for `listCreated`, `listMilestoneCreated` and `listUnlocked`; null otherwise.", "readOnly": true, "example": "lN6ZQycO", "examples": [ "lN6ZQycO" ] }, "documentId": { "type": [ "string", "null" ], "description": "The document this activity references. Set for `docCreated`; null otherwise.", "readOnly": true, "example": "ELe0nkum", "examples": [ "ELe0nkum" ] }, "fileId": { "type": [ "string", "null" ], "description": "The file this activity references. Set for `fileUploaded`; null otherwise.", "readOnly": true, "example": "xvM2toUM", "examples": [ "xvM2toUM" ] }, "memberId": { "type": [ "string", "null" ], "description": "The team member who joined or left. Set for `usersJoined` and `usersLeft`; null otherwise.", "readOnly": true, "example": "P3hYIKqK", "examples": [ "P3hYIKqK" ] }, "triggeredById": { "type": [ "string", "null" ], "description": "The team member who triggered this event, or null when it was triggered by an automation, an agent or a scheduled job. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "lvc47DE8", "examples": [ "lvc47DE8" ] } }, "required": [ "id", "createdAt", "projectId", "type" ], "additionalProperties": true }, "projectActivityExpanded": { "description": "A Project activity with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/projectActivity" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "list": { "allOf": [ { "$ref": "#/components/schemas/list" } ], "description": "The related List, present only when you pass `?expand=list`.", "x-example-omit": true }, "document": { "allOf": [ { "$ref": "#/components/schemas/document" } ], "description": "The related Document, present only when you pass `?expand=document`.", "x-example-omit": true }, "file": { "allOf": [ { "$ref": "#/components/schemas/file" } ], "description": "The related File, present only when you pass `?expand=file`.", "x-example-omit": true }, "triggeredBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=triggeredBy`.", "x-example-omit": true } } } ] }, "projectDashboard": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "udOQuo4n", "examples": [ "udOQuo4n" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the dashboard. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "projectId": { "type": "string", "minLength": 1, "description": "The project this dashboard belongs to. Set once on create; a dashboard cannot move between projects.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "isShared": { "type": "boolean", "description": "When true the dashboard is visible to all project members; when false it is private to whoever created it. Setting `isDefault: true` forces `isShared: true`.", "example": false, "examples": [ false ] }, "isDefault": { "type": "boolean", "description": "The project's default dashboard. Setting it to true also forces `isShared: true` and clears `isDefault` on the project's previous default — a project has at most one.", "example": false, "examples": [ false ] }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "fields", "members", "activity", "milestones", "tasks", "discussion", "docs", "files", "time", "reportChart" ], "description": "What the widget card renders." }, "config": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Opaque per-widget display settings. Pass `{}` unless you are mirroring the Nifty UI; the server stores whatever you send and returns it unchanged." }, "order": { "type": "integer", "description": "The widget card's position on the dashboard, starting at 0. A plain position — not the fractional rank used by `project.order` and `portfolio.order`. Derived from the order of the `widgets` array you send." }, "expanded": { "type": "boolean", "description": "Whether the widget card renders expanded." }, "resourceId": { "type": [ "string", "null" ], "description": "For `reportChart` widgets, the id of the report chart being rendered. null for every other widget type." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "order", "expanded" ], "additionalProperties": false }, "description": "Ordered widget cards owned by this dashboard. REPLACE semantics — the array you send becomes the complete widget set: omit the key to leave the widgets untouched, send `[]` to remove all of them, and re-send every widget you want to keep (any you leave out are deleted). Each widget's position comes from its index in the array.", "example": [], "examples": [ [] ] } }, "required": [ "id", "createdAt", "name", "projectId", "isShared", "isDefault" ], "additionalProperties": true }, "projectDashboardExpanded": { "description": "A Project Dashboard with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/projectDashboard" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "projectDashboardCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the dashboard. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "projectId": { "type": "string", "minLength": 1, "description": "The project this dashboard belongs to. Set once on create; a dashboard cannot move between projects.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true }, "isShared": { "type": "boolean", "description": "When true the dashboard is visible to all project members; when false it is private to whoever created it. Setting `isDefault: true` forces `isShared: true`.", "example": false, "examples": [ false ] }, "isDefault": { "type": "boolean", "description": "The project's default dashboard. Setting it to true also forces `isShared: true` and clears `isDefault` on the project's previous default — a project has at most one.", "example": false, "examples": [ false ] }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional. Pass the id of an existing widget on THIS dashboard to update it in place; any other value (or omitting it) creates a new widget with a server-assigned id." }, "type": { "type": "string", "enum": [ "fields", "members", "activity", "milestones", "tasks", "discussion", "docs", "files", "time", "reportChart" ], "description": "What the widget card renders." }, "config": { "type": "object", "additionalProperties": {}, "description": "Opaque per-widget display settings. Pass `{}` unless you are mirroring the Nifty UI; the server stores whatever you send and returns it unchanged." }, "expanded": { "type": "boolean", "description": "Whether the widget card renders expanded. Defaults to false." }, "resourceId": { "type": [ "string", "null" ], "description": "For `reportChart` widgets, the id of the report chart to render. null for every other widget type." } }, "required": [ "type" ], "additionalProperties": false }, "description": "Ordered widget cards owned by this dashboard. REPLACE semantics — the array you send becomes the complete widget set: omit the key to leave the widgets untouched, send `[]` to remove all of them, and re-send every widget you want to keep (any you leave out are deleted). Each widget's position comes from its index in the array.", "example": [], "examples": [ [] ] } }, "required": [ "name", "projectId" ], "additionalProperties": false }, "projectDashboardUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the dashboard. Maximum 100 characters.", "example": "Example", "examples": [ "Example" ] }, "isShared": { "type": "boolean", "description": "When true the dashboard is visible to all project members; when false it is private to whoever created it. Setting `isDefault: true` forces `isShared: true`.", "example": false, "examples": [ false ] }, "isDefault": { "type": "boolean", "description": "The project's default dashboard. Setting it to true also forces `isShared: true` and clears `isDefault` on the project's previous default — a project has at most one.", "example": false, "examples": [ false ] }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Optional. Pass the id of an existing widget on THIS dashboard to update it in place; any other value (or omitting it) creates a new widget with a server-assigned id." }, "type": { "type": "string", "enum": [ "fields", "members", "activity", "milestones", "tasks", "discussion", "docs", "files", "time", "reportChart" ], "description": "What the widget card renders." }, "config": { "type": "object", "additionalProperties": {}, "description": "Opaque per-widget display settings. Pass `{}` unless you are mirroring the Nifty UI; the server stores whatever you send and returns it unchanged." }, "expanded": { "type": "boolean", "description": "Whether the widget card renders expanded. Defaults to false." }, "resourceId": { "type": [ "string", "null" ], "description": "For `reportChart` widgets, the id of the report chart to render. null for every other widget type." } }, "required": [ "type" ], "additionalProperties": false }, "description": "Ordered widget cards owned by this dashboard. REPLACE semantics — the array you send becomes the complete widget set: omit the key to leave the widgets untouched, send `[]` to remove all of them, and re-send every widget you want to keep (any you leave out are deleted). Each widget's position comes from its index in the array.", "example": [], "examples": [ [] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "projectFolder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "0sSAIGwG", "examples": [ "0sSAIGwG" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Folder display name. Maximum 30 characters.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order of this project folder within its portfolio. Server-assigned on create; send a new value to reorder.", "example": 200, "examples": [ 200 ] }, "portfolioId": { "type": "string", "minLength": 1, "description": "The portfolio that contains this project folder. Required on create and immutable after — a folder cannot be moved between portfolios.", "example": "1YEYsy2X", "examples": [ "1YEYsy2X" ] } }, "required": [ "id", "createdAt", "name", "portfolioId" ], "additionalProperties": true }, "projectFolderExpanded": { "description": "A Project Folder with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/projectFolder" }, { "type": "object", "properties": { "portfolio": { "allOf": [ { "$ref": "#/components/schemas/portfolio" } ], "description": "The related Portfolio, present only when you pass `?expand=portfolio`.", "x-example-omit": true }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/project" }, "description": "The linked Project rows, present only when you pass `?expand=projects`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "projectFolderCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Folder display name. Maximum 30 characters.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order of this project folder within its portfolio. Server-assigned on create; send a new value to reorder.", "example": 200, "examples": [ 200 ] }, "portfolioId": { "type": "string", "minLength": 1, "description": "The portfolio that contains this project folder. Required on create and immutable after — a folder cannot be moved between portfolios.", "example": "1YEYsy2X", "examples": [ "1YEYsy2X" ], "x-createOnly": true } }, "required": [ "name", "portfolioId" ], "additionalProperties": false }, "projectFolderUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Folder display name. Maximum 30 characters.", "example": "Example", "examples": [ "Example" ] }, "order": { "type": [ "number", "null" ], "description": "Sort order of this project folder within its portfolio. Server-assigned on create; send a new value to reorder.", "example": 200, "examples": [ 200 ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "recurringRule": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "type": { "type": "string", "enum": [ "date", "status", "completion", "checkIn" ], "description": "What makes this rule fire. `date` — a `cron` or `schedule` timetable. `status` — the anchored task moving into `triggerStatusId`. `completion` — the anchored task being completed. Set once when the rule is created; it cannot be changed afterwards.", "example": "date", "examples": [ "date" ] }, "cron": { "type": [ "string", "null" ], "description": "Standard 5-field cron for `date` rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by `tzIana`.", "example": "0 9 * * 1", "examples": [ "0 9 * * 1" ] }, "schedule": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "null" } ], "description": "Recurrence timetable for `date` rules, as an alternative to `cron`. Send one or the other — if both are present, `cron` wins and `schedule` is ignored.", "example": {}, "examples": [ {} ] }, "cloneFields": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "description", "embedUrl", "startAt", "dueAt", "labels", "fields", "subtasks" ] } }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ], "description": "Restricts what each spawned task copies from the anchored task. **Omit it (or send null) and everything is copied** — this is an allowlist, not a set of extras. Allowed entries: `description`, `embedUrl`, `startAt`, `dueAt`, `labels`, `fields` (custom-field values), `subtasks`.", "example": [], "examples": [ [] ] }, "dateOffsets": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dueAt", "startAt" ] }, "offset": { "type": "integer" } }, "required": [ "type", "offset" ], "additionalProperties": false } }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ], "description": "Shifts dates on each spawned task, relative to the date it is spawned on: `[{ \"type\": \"dueAt\", \"offset\": 3 }]` gives every new task a due date 3 days out. `offset` is a whole number of days and may be negative.", "example": [], "examples": [ [] ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: `nextRecurrenceAt` and `sourceTaskId` are both cleared.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "weekParity": { "type": [ "string", "null" ], "enum": [ "off", "skipEvenWeeks", "skipOddWeeks" ], "description": "Thins a `date` recurrence out to every other ISO week. `off` (the default) fires every matching week; `skipEvenWeeks` fires only in odd ISO weeks; `skipOddWeeks` fires only in even ones.", "example": "off", "examples": [ "off" ] }, "recurOnDateOnly": { "type": [ "boolean", "null" ], "description": "For `date` rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.", "example": false, "examples": [ false ] }, "triggerStatusId": { "type": [ "string", "null" ], "description": "For `status` rules: the status whose arrival fires the rule — the next task is spawned when the anchored task moves into it. Required on a `status` rule and rejected on any other type. Set once when the rule is created.", "example": "7uM05NSk", "examples": [ "7uM05NSk" ] }, "onComplete": { "type": [ "boolean", "null" ], "description": "Read-only: true on `completion` rules, false on every other type. Derived from `type` — it is not part of the create body.", "readOnly": true, "example": false, "examples": [ false ] }, "sourceTaskId": { "type": [ "string", "null" ], "description": "The task this rule is anchored to. Required when the rule is created, and server-managed afterwards: each time the rule spawns, the engine repoints it at the newly created task, and it becomes null once `end` has passed — so a read can return a different task than you sent, or none.", "example": "5MM8V0rW", "examples": [ "5MM8V0rW" ] }, "nextRecurrenceAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Next occurrence (server-computed from cron/schedule + the author timezone snapshot). THE engine cursor — the nifty-crons poll selects rules by it; NEVER client-writable (a stale/forged value kills or force-spawns the rule).", "readOnly": true, "example": "2026-06-01T16:00:00.000Z", "examples": [ "2026-06-01T16:00:00.000Z" ] }, "targetStatusId": { "type": [ "string", "null" ], "description": "The status each spawned task is placed into — taken from the anchored task when the rule was created.", "readOnly": true, "example": "00taIogS", "examples": [ "00taIogS" ] }, "tzIana": { "type": [ "string", "null" ], "description": "The author's IANA timezone (e.g. 'America/New_York'), snapshotted server-side at create/update — the timezone the engine spawns occurrences in. Read-only display field; never client-writable.", "readOnly": true, "example": "America/New_York", "examples": [ "America/New_York" ] }, "tzOffset": { "type": [ "integer", "null" ], "description": "The author's UTC offset in MINUTES EAST of UTC at the time the rule was saved, matching `tzIana` (New York in winter is -300). Recorded by the server; never writable.", "readOnly": true, "example": 100, "examples": [ 100 ] } }, "required": [ "id", "createdAt", "type" ], "additionalProperties": true }, "recurringRuleExpanded": { "description": "A Recurring Rule with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/recurringRule" }, { "type": "object", "properties": { "sourceTask": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=sourceTask`.", "x-example-omit": true }, "targetStatus": { "allOf": [ { "$ref": "#/components/schemas/status" } ], "description": "The related Status, present only when you pass `?expand=targetStatus`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "recurringRuleCreate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "date", "status", "completion" ], "description": "What makes this rule fire. `date` — a `cron` or `schedule` timetable. `status` — the anchored task moving into `triggerStatusId`. `completion` — the anchored task being completed. Set once when the rule is created; it cannot be changed afterwards.", "example": "date", "examples": [ "date" ], "x-createOnly": true }, "sourceTaskId": { "type": "string", "minLength": 1, "description": "The task this rule is anchored to. Required when the rule is created, and server-managed afterwards: each time the rule spawns, the engine repoints it at the newly created task, and it becomes null once `end` has passed — so a read can return a different task than you sent, or none.", "example": "5MM8V0rW", "examples": [ "5MM8V0rW" ], "x-createOnly": true }, "cron": { "type": [ "string", "null" ], "minLength": 1, "description": "Standard 5-field cron for `date` rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by `tzIana`.", "example": "0 9 * * 1", "examples": [ "0 9 * * 1" ] }, "schedule": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Recurrence timetable for `date` rules, as an alternative to `cron`. Send one or the other — if both are present, `cron` wins and `schedule` is ignored.", "example": {}, "examples": [ {} ] }, "cloneFields": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "description", "embedUrl", "startAt", "dueAt", "labels", "fields", "subtasks" ] }, "description": "Restricts what each spawned task copies from the anchored task. **Omit it (or send null) and everything is copied** — this is an allowlist, not a set of extras. Allowed entries: `description`, `embedUrl`, `startAt`, `dueAt`, `labels`, `fields` (custom-field values), `subtasks`.", "example": [ "description" ], "examples": [ [ "description" ] ] }, "dateOffsets": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dueAt", "startAt" ] }, "offset": { "type": "integer" } }, "required": [ "type", "offset" ], "additionalProperties": false }, "description": "Shifts dates on each spawned task, relative to the date it is spawned on: `[{ \"type\": \"dueAt\", \"offset\": 3 }]` gives every new task a due date 3 days out. `offset` is a whole number of days and may be negative.", "example": [], "examples": [ [] ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: `nextRecurrenceAt` and `sourceTaskId` are both cleared.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "weekParity": { "type": "string", "enum": [ "off", "skipEvenWeeks", "skipOddWeeks" ], "description": "Thins a `date` recurrence out to every other ISO week. `off` (the default) fires every matching week; `skipEvenWeeks` fires only in odd ISO weeks; `skipOddWeeks` fires only in even ones.", "example": "off", "examples": [ "off" ] }, "recurOnDateOnly": { "type": "boolean", "description": "For `date` rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.", "example": false, "examples": [ false ] }, "triggerStatusId": { "type": [ "string", "null" ], "minLength": 1, "description": "For `status` rules: the status whose arrival fires the rule — the next task is spawned when the anchored task moves into it. Required on a `status` rule and rejected on any other type. Set once when the rule is created.", "example": "7uM05NSk", "examples": [ "7uM05NSk" ], "x-createOnly": true } }, "required": [ "type", "sourceTaskId" ], "additionalProperties": false }, "recurringRuleUpdate": { "type": "object", "properties": { "cron": { "type": [ "string", "null" ], "minLength": 1, "description": "Standard 5-field cron for `date` rules — minute, hour, day-of-month, month, day-of-week (no seconds field). It must resolve to a SINGLE minute and a SINGLE hour: ranges, lists and steps in those two positions are rejected. Occurrences are computed in the timezone reported by `tzIana`.", "example": "0 9 * * 1", "examples": [ "0 9 * * 1" ] }, "schedule": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Recurrence timetable for `date` rules, as an alternative to `cron`. Send one or the other — if both are present, `cron` wins and `schedule` is ignored.", "example": {}, "examples": [ {} ] }, "cloneFields": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "description", "embedUrl", "startAt", "dueAt", "labels", "fields", "subtasks" ] }, "description": "Restricts what each spawned task copies from the anchored task. **Omit it (or send null) and everything is copied** — this is an allowlist, not a set of extras. Allowed entries: `description`, `embedUrl`, `startAt`, `dueAt`, `labels`, `fields` (custom-field values), `subtasks`.", "example": [ "description" ], "examples": [ [ "description" ] ] }, "dateOffsets": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dueAt", "startAt" ] }, "offset": { "type": "integer" } }, "required": [ "type", "offset" ], "additionalProperties": false }, "description": "Shifts dates on each spawned task, relative to the date it is spawned on: `[{ \"type\": \"dueAt\", \"offset\": 3 }]` gives every new task a due date 3 days out. `offset` is a whole number of days and may be negative.", "example": [], "examples": [ [] ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "When the recurrence stops (ISO 8601 timestamp). It must fall after the next occurrence. Once passed, the rule stops spawning: `nextRecurrenceAt` and `sourceTaskId` are both cleared.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "weekParity": { "type": "string", "enum": [ "off", "skipEvenWeeks", "skipOddWeeks" ], "description": "Thins a `date` recurrence out to every other ISO week. `off` (the default) fires every matching week; `skipEvenWeeks` fires only in odd ISO weeks; `skipOddWeeks` fires only in even ones.", "example": "off", "examples": [ "off" ] }, "recurOnDateOnly": { "type": "boolean", "description": "For `date` rules: when true the rule fires strictly on its timetable, instead of also spawning early if the anchored task is completed ahead of schedule.", "example": false, "examples": [ false ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "reminder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "PHIAeeke", "examples": [ "PHIAeeke" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "date": { "type": "string", "format": "date-time", "description": "When the reminder fires, as an ISO 8601 instant (not a calendar date). Must be at least five minutes in the future. This is the only updatable field.", "example": "2026-09-01T09:00:00.000Z", "examples": [ "2026-09-01T09:00:00.000Z" ] }, "type": { "type": "string", "enum": [ "overdue", "custom" ], "description": "Reminder kind. `custom` is the only kind you can create — omit this field and you get it. `overdue` reminders also exist but Nifty creates them from task due dates; they are read-only and cannot be created, changed, or deleted through the API.", "example": "custom", "examples": [ "custom" ] }, "taskId": { "type": "string", "minLength": 1, "description": "The task this reminder is attached to. Required on create; immutable afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "createdById": { "type": [ "string", "null" ], "minLength": 1, "description": "The team member who created this reminder — also its notification recipient, since reminders are personal. Server-set; a member id, so resolve it with `GET /members/{id}`.", "readOnly": true, "example": "cRGcC2vM", "examples": [ "cRGcC2vM" ] } }, "required": [ "id", "createdAt", "date", "type", "taskId" ], "additionalProperties": true }, "reminderExpanded": { "description": "A Reminder with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/reminder" }, { "type": "object", "properties": { "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "reminderCreate": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "When the reminder fires, as an ISO 8601 instant (not a calendar date). Must be at least five minutes in the future. This is the only updatable field.", "example": "2026-09-01T09:00:00.000Z", "examples": [ "2026-09-01T09:00:00.000Z" ] }, "type": { "type": "string", "enum": [ "custom" ], "default": "custom", "description": "Reminder kind. `custom` is the only kind you can create — omit this field and you get it. `overdue` reminders also exist but Nifty creates them from task due dates; they are read-only and cannot be created, changed, or deleted through the API.", "example": "custom", "examples": [ "custom" ], "x-createOnly": true }, "taskId": { "type": "string", "minLength": 1, "description": "The task this reminder is attached to. Required on create; immutable afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ], "x-createOnly": true } }, "required": [ "date", "taskId" ], "additionalProperties": false }, "reminderUpdate": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "When the reminder fires, as an ISO 8601 instant (not a calendar date). Must be at least five minutes in the future. This is the only updatable field.", "example": "2026-09-01T09:00:00.000Z", "examples": [ "2026-09-01T09:00:00.000Z" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "reportChart": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "Z3hEUMCq", "examples": [ "Z3hEUMCq" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "dataType": { "type": "string", "enum": [ "live", "events", "historical" ], "description": "Aggregation mode for the chart: `live`, `events`, or `historical`.", "example": "live", "examples": [ "live" ] }, "chartType": { "type": "string", "enum": [ "line", "bar", "area", "areaStacked", "pie", "table", "number", "funnel" ], "description": "Visualization type: `line`, `bar`, `area`, `areaStacked`, `pie`, `table`, `number`, or `funnel`.", "example": "line", "examples": [ "line" ] }, "dateRange": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "An identifier of your own for the range (a preset key, say). Stored verbatim and never interpreted." }, "start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the window (ISO 8601)." }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the window (ISO 8601)." } }, "additionalProperties": true, "description": "Restricts the chart to a window of time. Omitted is stored (and read back) as `{}` rather than null.", "example": {}, "examples": [ {} ] }, "filter": { "type": [ "object", "null" ], "properties": { "term": { "type": "string", "description": "Free-text match on the task name." }, "projectId": { "type": "string", "description": "Narrow to one of the chart's projects." }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Assignees to include. The literal `unassigned` matches tasks with nobody on them." }, "dueDate": { "type": "object", "properties": { "start": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": true, "description": "Only tasks whose due date falls in this window." }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Lists to include." }, "statusIds": { "type": "array", "items": { "type": "string" }, "description": "Board columns to include." }, "labelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels to include." }, "memberLabelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels applied to PEOPLE — matches tasks assigned to them." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "The custom field to filter on." }, "type": { "type": "string", "description": "The custom field's kind." }, "value": { "description": "The value to match." } }, "additionalProperties": true }, "description": "Custom-field facets, one entry per field." } }, "additionalProperties": true, "description": "Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as `{}` rather than null.", "example": {}, "examples": [ {} ] }, "series": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "metric": { "type": "string", "description": "What to measure: `count`, `story_points`, `tracked_time`, or a custom-field id." }, "operator": { "type": "string", "description": "How to combine it: `sum`, `average`, `median`, `min` or `max`." }, "taskSet": { "type": "string", "description": "Which tasks to measure. For `live` and `historical` charts: `all_tasks`, `open_tasks` or `completed_tasks`. For `events` charts: `count`, `story_points` or `tracked_time`." }, "color": { "type": "string", "description": "Hex color for this series." }, "name": { "type": "string", "description": "Label shown in the chart legend." }, "filter": { "type": "object", "properties": { "term": { "type": "string", "description": "Free-text match on the task name." }, "projectId": { "type": "string", "description": "Narrow to one of the chart's projects." }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Assignees to include. The literal `unassigned` matches tasks with nobody on them." }, "dueDate": { "type": "object", "properties": { "start": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": true, "description": "Only tasks whose due date falls in this window." }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Lists to include." }, "statusIds": { "type": "array", "items": { "type": "string" }, "description": "Board columns to include." }, "labelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels to include." }, "memberLabelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels applied to PEOPLE — matches tasks assigned to them." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "The custom field to filter on." }, "type": { "type": "string", "description": "The custom field's kind." }, "value": { "description": "The value to match." } }, "additionalProperties": true }, "description": "Custom-field facets, one entry per field." } }, "additionalProperties": true, "description": "Narrows this series further, on top of the chart-level filter." } }, "additionalProperties": true }, "description": "The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as `[]`); send it and it must have at least one entry.", "example": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "examples": [ [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ] ] }, "name": { "type": [ "string", "null" ], "description": "Optional display name for the chart.", "example": "Example", "examples": [ "Example" ] }, "projects": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The projects whose tasks this chart aggregates. At least one is required when the chart is created. Read them back with `?expand=projects`, or edit them one at a time via `POST`/`DELETE /report-charts/{id}/projects`.", "example": [ "iV6vIU8N" ], "examples": [ [ "iV6vIU8N" ] ] } }, "required": [ "id", "createdAt", "dataType", "chartType" ], "additionalProperties": true }, "reportChartExpanded": { "description": "A Report Chart with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/reportChart" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "reportChartCreate": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "The projects whose tasks this chart aggregates. At least one is required. On update, use `POST`/`DELETE /report-charts/{id}/projects`.", "example": [ "iV6vIU8N" ], "examples": [ [ "iV6vIU8N" ] ] }, "dataType": { "type": "string", "enum": [ "live", "events", "historical" ], "description": "Aggregation mode for the chart: `live`, `events`, or `historical`.", "example": "live", "examples": [ "live" ] }, "chartType": { "type": "string", "enum": [ "line", "bar", "area", "areaStacked", "pie", "table", "number", "funnel" ], "description": "Visualization type: `line`, `bar`, `area`, `areaStacked`, `pie`, `table`, `number`, or `funnel`.", "example": "line", "examples": [ "line" ] }, "dateRange": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "An identifier of your own for the range (a preset key, say). Stored verbatim and never interpreted." }, "start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the window (ISO 8601)." }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the window (ISO 8601)." } }, "additionalProperties": true, "description": "Restricts the chart to a window of time. Omitted is stored (and read back) as `{}` rather than null.", "example": {}, "examples": [ {} ] }, "filter": { "type": [ "object", "null" ], "properties": { "term": { "type": "string", "description": "Free-text match on the task name." }, "projectId": { "type": "string", "description": "Narrow to one of the chart's projects." }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Assignees to include. The literal `unassigned` matches tasks with nobody on them." }, "dueDate": { "type": "object", "properties": { "start": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": true, "description": "Only tasks whose due date falls in this window." }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Lists to include." }, "statusIds": { "type": "array", "items": { "type": "string" }, "description": "Board columns to include." }, "labelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels to include." }, "memberLabelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels applied to PEOPLE — matches tasks assigned to them." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "The custom field to filter on." }, "type": { "type": "string", "description": "The custom field's kind." }, "value": { "description": "The value to match." } }, "additionalProperties": true }, "description": "Custom-field facets, one entry per field." } }, "additionalProperties": true, "description": "Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as `{}` rather than null.", "example": {}, "examples": [ {} ] }, "series": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "metric": { "type": "string", "description": "What to measure: `count`, `story_points`, `tracked_time`, or a custom-field id." }, "operator": { "type": "string", "description": "How to combine it: `sum`, `average`, `median`, `min` or `max`." }, "taskSet": { "type": "string", "description": "Which tasks to measure. For `live` and `historical` charts: `all_tasks`, `open_tasks` or `completed_tasks`. For `events` charts: `count`, `story_points` or `tracked_time`." }, "color": { "type": "string", "description": "Hex color for this series." }, "name": { "type": "string", "description": "Label shown in the chart legend." }, "filter": { "type": "object", "properties": { "term": { "type": "string", "description": "Free-text match on the task name." }, "projectId": { "type": "string", "description": "Narrow to one of the chart's projects." }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Assignees to include. The literal `unassigned` matches tasks with nobody on them." }, "dueDate": { "type": "object", "properties": { "start": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": true, "description": "Only tasks whose due date falls in this window." }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Lists to include." }, "statusIds": { "type": "array", "items": { "type": "string" }, "description": "Board columns to include." }, "labelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels to include." }, "memberLabelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels applied to PEOPLE — matches tasks assigned to them." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "The custom field to filter on." }, "type": { "type": "string", "description": "The custom field's kind." }, "value": { "description": "The value to match." } }, "additionalProperties": true }, "description": "Custom-field facets, one entry per field." } }, "additionalProperties": true, "description": "Narrows this series further, on top of the chart-level filter." } }, "additionalProperties": true }, "minItems": 1, "description": "The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as `[]`); send it and it must have at least one entry.", "example": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "examples": [ [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ] ] }, "name": { "type": [ "string", "null" ], "description": "Optional display name for the chart.", "example": "Example", "examples": [ "Example" ] } }, "required": [ "dataType", "chartType", "projects" ], "additionalProperties": false }, "reportChartUpdate": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "The projects whose tasks this chart aggregates. At least one is required. On update, use `POST`/`DELETE /report-charts/{id}/projects`.", "example": [ "iV6vIU8N" ], "examples": [ [ "iV6vIU8N" ] ] }, "dataType": { "type": "string", "enum": [ "live", "events", "historical" ], "description": "Aggregation mode for the chart: `live`, `events`, or `historical`.", "example": "live", "examples": [ "live" ] }, "chartType": { "type": "string", "enum": [ "line", "bar", "area", "areaStacked", "pie", "table", "number", "funnel" ], "description": "Visualization type: `line`, `bar`, `area`, `areaStacked`, `pie`, `table`, `number`, or `funnel`.", "example": "line", "examples": [ "line" ] }, "dateRange": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "An identifier of your own for the range (a preset key, say). Stored verbatim and never interpreted." }, "start": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the window (ISO 8601)." }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the window (ISO 8601)." } }, "additionalProperties": true, "description": "Restricts the chart to a window of time. Omitted is stored (and read back) as `{}` rather than null.", "example": {}, "examples": [ {} ] }, "filter": { "type": [ "object", "null" ], "properties": { "term": { "type": "string", "description": "Free-text match on the task name." }, "projectId": { "type": "string", "description": "Narrow to one of the chart's projects." }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Assignees to include. The literal `unassigned` matches tasks with nobody on them." }, "dueDate": { "type": "object", "properties": { "start": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": true, "description": "Only tasks whose due date falls in this window." }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Lists to include." }, "statusIds": { "type": "array", "items": { "type": "string" }, "description": "Board columns to include." }, "labelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels to include." }, "memberLabelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels applied to PEOPLE — matches tasks assigned to them." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "The custom field to filter on." }, "type": { "type": "string", "description": "The custom field's kind." }, "value": { "description": "The value to match." } }, "additionalProperties": true }, "description": "Custom-field facets, one entry per field." } }, "additionalProperties": true, "description": "Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as `{}` rather than null.", "example": {}, "examples": [ {} ] }, "series": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "metric": { "type": "string", "description": "What to measure: `count`, `story_points`, `tracked_time`, or a custom-field id." }, "operator": { "type": "string", "description": "How to combine it: `sum`, `average`, `median`, `min` or `max`." }, "taskSet": { "type": "string", "description": "Which tasks to measure. For `live` and `historical` charts: `all_tasks`, `open_tasks` or `completed_tasks`. For `events` charts: `count`, `story_points` or `tracked_time`." }, "color": { "type": "string", "description": "Hex color for this series." }, "name": { "type": "string", "description": "Label shown in the chart legend." }, "filter": { "type": "object", "properties": { "term": { "type": "string", "description": "Free-text match on the task name." }, "projectId": { "type": "string", "description": "Narrow to one of the chart's projects." }, "memberIds": { "type": "array", "items": { "type": "string" }, "description": "Assignees to include. The literal `unassigned` matches tasks with nobody on them." }, "dueDate": { "type": "object", "properties": { "start": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "end": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] } }, "additionalProperties": true, "description": "Only tasks whose due date falls in this window." }, "listIds": { "type": "array", "items": { "type": "string" }, "description": "Lists to include." }, "statusIds": { "type": "array", "items": { "type": "string" }, "description": "Board columns to include." }, "labelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels to include." }, "memberLabelIds": { "type": "array", "items": { "type": "string" }, "description": "Labels applied to PEOPLE — matches tasks assigned to them." }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "description": "The custom field to filter on." }, "type": { "type": "string", "description": "The custom field's kind." }, "value": { "description": "The value to match." } }, "additionalProperties": true }, "description": "Custom-field facets, one entry per field." } }, "additionalProperties": true, "description": "Narrows this series further, on top of the chart-level filter." } }, "additionalProperties": true }, "minItems": 1, "description": "The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as `[]`); send it and it must have at least one entry.", "example": [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ], "examples": [ [ { "metric": "count", "operator": "sum", "taskSet": "open_tasks", "color": "#00A99B", "name": "Open tasks", "filter": {} } ] ] }, "name": { "type": [ "string", "null" ], "description": "Optional display name for the chart.", "example": "Example", "examples": [ "Example" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "role": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier — an opaque string; never parse or generate one.", "readOnly": true, "example": "zngY4nUy", "examples": [ "zngY4nUy" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "description": "The role's name, unique within the workspace. Cannot be `owner`, `manager`, `regular` or `client` — those four are built in.", "example": "Example", "examples": [ "Example" ] }, "editable": { "type": "boolean", "description": "False for the four built-in roles (owner, manager, regular, client). Those cannot be renamed, re-permissioned or deleted — only `initialScreen` may change.", "readOnly": true, "example": false, "examples": [ false ] }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "editTeam", "inviteToTeam", "removeFromTeam", "viewTeamSettings", "viewTeamOverview", "editRole", "editBilling", "createSubteam", "editSubteam", "removeSubteam", "createProject", "editProject", "removeProject", "inviteToProject", "removeFromProject", "viewProjectSettings", "createMilestone", "editMilestone", "removeMilestone", "createTaskGroup", "editTaskGroup", "removeTaskGroup", "createTask", "editTask", "removeTask", "assignToTask", "unassignFromTask", "createSubtask", "editSubtask", "removeSubtask", "assignToSubtask", "unassignFromSubtask", "addFile", "removeFile", "createDoc", "getUserReport", "getProjectReport", "getTeamReport", "startStopTimer", "addManualTime", "editTimer", "removeTimer", "viewChat", "viewAllTasks", "viewMemberEmail", "viewTeamClients", "leaveTeam", "editUser", "viewUserActivity", "viewUserLabels", "viewClientUserLabels", "viewSubteam", "leaveProject", "viewProjectClients", "createProjectTemplate", "publicShareMilestones", "publicShareTasks", "fullChat", "pinMessage", "createCustomFields", "editCustomFields", "removeCustomFields", "canPlayTour", "seeUpgradeFeatures", "viewTimeReports", "moveTask", "hideTask", "createFolder", "editFolder", "removeFolder", "editFile", "ownerChat", "projectAutomations", "createLabel", "editLabel", "removeLabel", "guestChat", "completeTask", "completeSubtask", "createForm", "createTemplate", "viewTemplate", "editTemplate", "removeTemplate", "editForm", "removeForm", "createGoal", "editGoal", "removeGoal", "viewGoal", "viewInbox", "viewFavorites", "editTaskDates", "createApps", "editMessage", "saveUserStatusTemplate", "removeUserStatusTemplate", "createUserEvent", "editUserEvent", "removeUserEvent", "inviteToChat", "removeFromChat", "editChat", "removeChat", "editTeamRootProps", "createProjectFolder", "editProjectFolder", "removeProjectFolder", "createCheckIn", "editCheckIn", "removeCheckIn", "viewCheckIn", "createChart", "editChart", "removeChart", "createDashboard", "editDashboard", "removeDashboard", "manageAgents", "manageWebhooks", "hideMessage" ] }, "description": "The permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending `[]`) means the role grants nothing. **You may only grant permissions you hold yourself**; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.", "example": [ "createTask", "editTask", "viewAllTasks" ], "examples": [ [ "createTask", "editTask", "viewAllTasks" ] ] }, "initialScreen": { "type": "string", "enum": [ "default", "allTasks", "createTask", "calendar", "overview", "workloads" ], "description": "The screen members holding this role land on when they open the workspace.", "example": "allTasks", "examples": [ "allTasks" ] } }, "required": [ "id", "createdAt", "name", "editable", "permissions", "initialScreen" ], "additionalProperties": true }, "roleExpanded": { "description": "A Role with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/role" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true } } } ] }, "roleCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The role's name, unique within the workspace. Cannot be `owner`, `manager`, `regular` or `client` — those four are built in.", "example": "Example", "examples": [ "Example" ] }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "editTeam", "inviteToTeam", "removeFromTeam", "viewTeamSettings", "viewTeamOverview", "editRole", "editBilling", "createSubteam", "editSubteam", "removeSubteam", "createProject", "editProject", "removeProject", "inviteToProject", "removeFromProject", "viewProjectSettings", "createMilestone", "editMilestone", "removeMilestone", "createTaskGroup", "editTaskGroup", "removeTaskGroup", "createTask", "editTask", "removeTask", "assignToTask", "unassignFromTask", "createSubtask", "editSubtask", "removeSubtask", "assignToSubtask", "unassignFromSubtask", "addFile", "removeFile", "createDoc", "getUserReport", "getProjectReport", "getTeamReport", "startStopTimer", "addManualTime", "editTimer", "removeTimer", "viewChat", "viewAllTasks", "viewMemberEmail", "viewTeamClients", "leaveTeam", "editUser", "viewUserActivity", "viewUserLabels", "viewClientUserLabels", "viewSubteam", "leaveProject", "viewProjectClients", "createProjectTemplate", "publicShareMilestones", "publicShareTasks", "fullChat", "pinMessage", "createCustomFields", "editCustomFields", "removeCustomFields", "canPlayTour", "seeUpgradeFeatures", "viewTimeReports", "moveTask", "hideTask", "createFolder", "editFolder", "removeFolder", "editFile", "ownerChat", "projectAutomations", "createLabel", "editLabel", "removeLabel", "guestChat", "completeTask", "completeSubtask", "createForm", "createTemplate", "viewTemplate", "editTemplate", "removeTemplate", "editForm", "removeForm", "createGoal", "editGoal", "removeGoal", "viewGoal", "viewInbox", "viewFavorites", "editTaskDates", "createApps", "editMessage", "saveUserStatusTemplate", "removeUserStatusTemplate", "createUserEvent", "editUserEvent", "removeUserEvent", "inviteToChat", "removeFromChat", "editChat", "removeChat", "editTeamRootProps", "createProjectFolder", "editProjectFolder", "removeProjectFolder", "createCheckIn", "editCheckIn", "removeCheckIn", "viewCheckIn", "createChart", "editChart", "removeChart", "createDashboard", "editDashboard", "removeDashboard", "manageAgents", "manageWebhooks", "hideMessage" ] }, "description": "The permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending `[]`) means the role grants nothing. **You may only grant permissions you hold yourself**; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.", "example": [ "createTask", "editTask", "viewAllTasks" ], "examples": [ [ "createTask", "editTask", "viewAllTasks" ] ] }, "initialScreen": { "type": "string", "enum": [ "default", "allTasks", "createTask", "calendar", "overview", "workloads" ], "description": "The screen members holding this role land on when they open the workspace.", "example": "allTasks", "examples": [ "allTasks" ] } }, "required": [ "name" ], "additionalProperties": false }, "roleUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The role's name, unique within the workspace. Cannot be `owner`, `manager`, `regular` or `client` — those four are built in.", "example": "Example", "examples": [ "Example" ] }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "editTeam", "inviteToTeam", "removeFromTeam", "viewTeamSettings", "viewTeamOverview", "editRole", "editBilling", "createSubteam", "editSubteam", "removeSubteam", "createProject", "editProject", "removeProject", "inviteToProject", "removeFromProject", "viewProjectSettings", "createMilestone", "editMilestone", "removeMilestone", "createTaskGroup", "editTaskGroup", "removeTaskGroup", "createTask", "editTask", "removeTask", "assignToTask", "unassignFromTask", "createSubtask", "editSubtask", "removeSubtask", "assignToSubtask", "unassignFromSubtask", "addFile", "removeFile", "createDoc", "getUserReport", "getProjectReport", "getTeamReport", "startStopTimer", "addManualTime", "editTimer", "removeTimer", "viewChat", "viewAllTasks", "viewMemberEmail", "viewTeamClients", "leaveTeam", "editUser", "viewUserActivity", "viewUserLabels", "viewClientUserLabels", "viewSubteam", "leaveProject", "viewProjectClients", "createProjectTemplate", "publicShareMilestones", "publicShareTasks", "fullChat", "pinMessage", "createCustomFields", "editCustomFields", "removeCustomFields", "canPlayTour", "seeUpgradeFeatures", "viewTimeReports", "moveTask", "hideTask", "createFolder", "editFolder", "removeFolder", "editFile", "ownerChat", "projectAutomations", "createLabel", "editLabel", "removeLabel", "guestChat", "completeTask", "completeSubtask", "createForm", "createTemplate", "viewTemplate", "editTemplate", "removeTemplate", "editForm", "removeForm", "createGoal", "editGoal", "removeGoal", "viewGoal", "viewInbox", "viewFavorites", "editTaskDates", "createApps", "editMessage", "saveUserStatusTemplate", "removeUserStatusTemplate", "createUserEvent", "editUserEvent", "removeUserEvent", "inviteToChat", "removeFromChat", "editChat", "removeChat", "editTeamRootProps", "createProjectFolder", "editProjectFolder", "removeProjectFolder", "createCheckIn", "editCheckIn", "removeCheckIn", "viewCheckIn", "createChart", "editChart", "removeChart", "createDashboard", "editDashboard", "removeDashboard", "manageAgents", "manageWebhooks", "hideMessage" ] }, "description": "The permissions this role grants. Send names; an unknown name is rejected with 400, and omitting the field (or sending `[]`) means the role grants nothing. **You may only grant permissions you hold yourself**; on update this is judged on the delta, so permissions the role already had can be carried forward untouched.", "example": [ "createTask", "editTask", "viewAllTasks" ], "examples": [ [ "createTask", "editTask", "viewAllTasks" ] ] }, "initialScreen": { "type": "string", "enum": [ "default", "allTasks", "createTask", "calendar", "overview", "workloads" ], "description": "The screen members holding this role land on when they open the workspace.", "example": "allTasks", "examples": [ "allTasks" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "status": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "5aM4ncwI", "examples": [ "5aM4ncwI" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "name": { "type": "string", "description": "Status column name (e.g. \"To Do\", \"In Progress\"). 1–100 characters after trimming.", "example": "Example", "examples": [ "Example" ] }, "color": { "type": [ "string", "null" ], "description": "Hex color (`#RGB` or `#RRGGBB`, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "archived": { "type": "boolean", "description": "Whether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no `archivedAt`/`archivedById` stamp — use the audit log if you need to know who archived it and when.", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this status column belongs to. Set once on create — a status cannot be moved to another project.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "listId": { "type": [ "string", "null" ], "description": "When this status column is also rendered as a list, the id of that list. Null otherwise.", "readOnly": true, "example": "lN6ZQycO", "examples": [ "lN6ZQycO" ] } }, "required": [ "id", "createdAt", "name", "archived", "projectId" ], "additionalProperties": true }, "statusExpanded": { "description": "A Status with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/status" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=assignees`.", "x-example-omit": true }, "hiddenFor": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The linked Role rows, present only when you pass `?expand=hiddenFor`.", "x-example-omit": true }, "list": { "allOf": [ { "$ref": "#/components/schemas/list" } ], "description": "The related List, present only when you pass `?expand=list`.", "x-example-omit": true }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The linked Task rows, present only when you pass `?expand=tasks`.", "x-example-omit": true }, "recurringRules": { "type": "array", "items": { "$ref": "#/components/schemas/recurringRule" }, "description": "The linked Recurring Rule rows, present only when you pass `?expand=recurringRules`.", "x-example-omit": true } } } ] }, "statusCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Status column name (e.g. \"To Do\", \"In Progress\"). 1–100 characters after trimming.", "example": "Example", "examples": [ "Example" ] }, "color": { "type": [ "string", "null" ], "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$", "description": "Hex color (`#RGB` or `#RRGGBB`, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "archived": { "type": "boolean", "description": "Whether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no `archivedAt`/`archivedById` stamp — use the audit log if you need to know who archived it and when.", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this status column belongs to. Set once on create — a status cannot be moved to another project.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true } }, "required": [ "name", "projectId" ], "additionalProperties": false }, "statusUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Status column name (e.g. \"To Do\", \"In Progress\"). 1–100 characters after trimming.", "example": "Example", "examples": [ "Example" ] }, "color": { "type": [ "string", "null" ], "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$", "description": "Hex color (`#RGB` or `#RRGGBB`, case-insensitive). Omit it on create and Nifty assigns one from its palette, so a status created through the API is never colorless.", "example": "#00A99B", "examples": [ "#00A99B" ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the column within the project. Omit it on create and the server appends the column at the end. To reposition, send the midpoint of the two neighbours' ranks.", "example": 100, "examples": [ 100 ] }, "archived": { "type": "boolean", "description": "Whether this status column is archived (hidden from active boards but not deleted). Regular field, NOT a soft-delete. Unlike an archived task, an archived status carries no `archivedAt`/`archivedById` stamp — use the audit log if you need to know who archived it and when.", "example": false, "examples": [ false ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "task": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "archived": { "type": "boolean", "description": "Whether this resource is archived.", "example": false, "examples": [ false ] }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the task was archived. Server-stamped from the `archived` boolean — not directly writable.", "readOnly": true, "example": "2026-06-05T12:00:00.000Z", "examples": [ "2026-06-05T12:00:00.000Z" ] }, "archivedById": { "type": [ "string", "null" ], "description": "Member who archived this resource (server-stamped). A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "5S69rsOO", "examples": [ "5S69rsOO" ] }, "niceId": { "type": [ "integer", "null" ], "description": "Per-project sequential counter assigned on insert. Compose with `project.niceId` for human-readable references (e.g. \"PROJ-42\"). Server-managed — read-only on the wire.", "readOnly": true, "example": 1234, "examples": [ 1234 ] }, "name": { "type": "string", "minLength": 1, "description": "Task name. 1–1024 characters after trimming. Content that reads as promotional (link-farm text, bulk marketing copy) is rejected with a 400.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Task description. Supports Markdown formatting.", "example": "A concise description.", "examples": [ "A concise description." ] }, "completed": { "type": "boolean", "description": "Whether this task is marked complete. Set `true` to mark a task done — Nifty renders completed tasks in a virtual \"Completed\" column, so prefer this over creating a separate \"Done\" status. Pairs with `completedAt` (timestamp) and `completedById` (who completed it).", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this task belongs to. Required on create; PATCH-ing it moves the task — and its subtasks — into another project.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "listId": { "type": [ "string", "null" ], "description": "The list this task belongs to. Null when the task is not on a list. Legal ids come from `GET /lists`.", "example": "lN6ZQycO", "examples": [ "lN6ZQycO" ] }, "statusId": { "type": [ "string", "null" ], "description": "The status column this task sits in. Null when the task has no status (e.g. a backlog item). Legal ids come from `GET /statuses`.", "example": "5aM4ncwI", "examples": [ "5aM4ncwI" ] }, "parentTaskId": { "type": [ "string", "null" ], "description": "The parent task, when this task is a subtask. Null on top-level tasks. Subtask siblings are ranked by `order`.", "example": "4KOocqYo", "examples": [ "4KOocqYo" ] }, "dependencyId": { "type": [ "string", "null" ], "description": "The single task this one waits on. Nifty models one predecessor per task, so this is an id and not an array. Null when the task has no predecessor.", "example": "i9TUmOWm", "examples": [ "i9TUmOWm" ] }, "recurringRuleId": { "type": [ "string", "null" ], "description": "The recurrence rule that regenerates this task, for recurring tasks. Null otherwise. Legal ids come from `GET /recurring-rules`.", "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] }, "startAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When work on this task is scheduled to start.", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this task is due.", "example": "2026-06-07T12:00:00.000Z", "examples": [ "2026-06-07T12:00:00.000Z" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the task was marked complete. Server-stamped from the `completed` boolean — not directly writable.", "readOnly": true, "example": "2026-06-03T12:00:00.000Z", "examples": [ "2026-06-03T12:00:00.000Z" ] }, "remindAt": { "type": [ "string", "null" ], "format": "date-time", "description": "A single reminder time for this task. Recurring or multiple reminders are separate objects on the `reminder` resource (`GET /reminders?taskId[eq]=…`).", "example": "2026-06-04T02:00:00.000Z", "examples": [ "2026-06-04T02:00:00.000Z" ] }, "storyPoints": { "type": [ "number", "null" ], "description": "Story points used for agile estimation; client-supplied.", "example": 100, "examples": [ 100 ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the task in its default ordering. To reposition, send the midpoint of the two neighbours' ranks. Two subtasks under the same parent cannot share a rank.", "example": 100, "examples": [ 100 ] }, "orderList": { "type": [ "number", "null" ], "description": "Fractional rank of the task within its list. Same read/write shape and midpoint recipe as `order`.", "example": 100, "examples": [ 100 ] }, "banner": { "type": [ "string", "null" ], "description": "Cover image URL rendered at the top of the task detail view.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "embedUrl": { "type": [ "string", "null" ], "description": "External URL embedded in the task body (e.g. Loom recording, Figma frame).", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "createdById": { "type": [ "string", "null" ], "description": "The team member who created this task. Server-set. Resolve it with `?expand=createdBy` or `GET /members/{id}`; pairs with `archivedById` and `completedById`. This is a member id — `createdByActorId` is a different identifier space and `GET /members/{id}` will not accept it.", "readOnly": true, "example": "njWQkGgk", "examples": [ "njWQkGgk" ] }, "completedById": { "type": [ "string", "null" ], "description": "The team member who marked the task complete. Server-set when `completed` flips; pairs with `completedAt`. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "Kbmwwoue", "examples": [ "Kbmwwoue" ] } }, "required": [ "id", "createdAt", "archived", "name", "completed", "projectId" ], "additionalProperties": true }, "taskExpanded": { "description": "A Task with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/task" }, { "type": "object", "properties": { "project": { "allOf": [ { "$ref": "#/components/schemas/project" } ], "description": "The related Project, present only when you pass `?expand=project`.", "x-example-omit": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/status" } ], "description": "The related Status, present only when you pass `?expand=status`.", "x-example-omit": true }, "list": { "allOf": [ { "$ref": "#/components/schemas/list" } ], "description": "The related List, present only when you pass `?expand=list`.", "x-example-omit": true }, "parentTask": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=parentTask`.", "x-example-omit": true }, "dependency": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=dependency`.", "x-example-omit": true }, "recurringRule": { "allOf": [ { "$ref": "#/components/schemas/recurringRule" } ], "description": "The related Recurring Rule, present only when you pass `?expand=recurringRule`.", "x-example-omit": true }, "createdBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=createdBy`.", "x-example-omit": true }, "archivedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=archivedBy`.", "x-example-omit": true }, "completedBy": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=completedBy`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true }, "assignees": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=assignees`.", "x-example-omit": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/label" }, "description": "The linked Label rows, present only when you pass `?expand=labels`.", "x-example-omit": true }, "subscribers": { "type": "array", "items": { "$ref": "#/components/schemas/member" }, "description": "The linked Team Member rows, present only when you pass `?expand=subscribers`.", "x-example-omit": true }, "hiddenFor": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "description": "The linked Role rows, present only when you pass `?expand=hiddenFor`.", "x-example-omit": true }, "connectedTasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The linked Task rows, present only when you pass `?expand=connectedTasks`.", "x-example-omit": true }, "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/task" }, "description": "The linked Task rows, present only when you pass `?expand=subtasks`.", "x-example-omit": true }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/message" }, "description": "The linked Message rows, present only when you pass `?expand=messages`.", "x-example-omit": true }, "checklists": { "type": "array", "items": { "$ref": "#/components/schemas/checklist" }, "description": "The linked Checklist rows, present only when you pass `?expand=checklists`.", "x-example-omit": true }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/file" }, "description": "The linked File rows, present only when you pass `?expand=files`.", "x-example-omit": true }, "customFields": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The linked attachedCustomField rows, present only when you pass `?expand=customFields`.", "x-example-omit": true } } } ] }, "taskCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Task name. 1–1024 characters after trimming. Content that reads as promotional (link-farm text, bulk marketing copy) is rejected with a 400.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Task description. Supports Markdown formatting.", "example": "A concise description.", "examples": [ "A concise description." ] }, "archived": { "type": "boolean", "description": "Whether this resource is archived.", "example": false, "examples": [ false ] }, "completed": { "type": "boolean", "description": "Whether this task is marked complete. Set `true` to mark a task done — Nifty renders completed tasks in a virtual \"Completed\" column, so prefer this over creating a separate \"Done\" status. Pairs with `completedAt` (timestamp) and `completedById` (who completed it).", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this task belongs to. Required on create; PATCH-ing it moves the task — and its subtasks — into another project.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "listId": { "type": [ "string", "null" ], "description": "The list this task belongs to. Null when the task is not on a list. Legal ids come from `GET /lists`.", "example": "lN6ZQycO", "examples": [ "lN6ZQycO" ] }, "statusId": { "type": [ "string", "null" ], "description": "The status column this task sits in. Null when the task has no status (e.g. a backlog item). Legal ids come from `GET /statuses`.", "example": "5aM4ncwI", "examples": [ "5aM4ncwI" ] }, "parentTaskId": { "type": [ "string", "null" ], "description": "The parent task, when this task is a subtask. Null on top-level tasks. Subtask siblings are ranked by `order`.", "example": "4KOocqYo", "examples": [ "4KOocqYo" ] }, "dependencyId": { "type": [ "string", "null" ], "description": "The single task this one waits on. Nifty models one predecessor per task, so this is an id and not an array. Null when the task has no predecessor.", "example": "i9TUmOWm", "examples": [ "i9TUmOWm" ] }, "recurringRuleId": { "type": [ "string", "null" ], "description": "The recurrence rule that regenerates this task, for recurring tasks. Null otherwise. Legal ids come from `GET /recurring-rules`.", "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] }, "startAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When work on this task is scheduled to start.", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this task is due.", "example": "2026-06-07T12:00:00.000Z", "examples": [ "2026-06-07T12:00:00.000Z" ] }, "remindAt": { "type": [ "string", "null" ], "format": "date-time", "description": "A single reminder time for this task. Recurring or multiple reminders are separate objects on the `reminder` resource (`GET /reminders?taskId[eq]=…`).", "example": "2026-06-04T02:00:00.000Z", "examples": [ "2026-06-04T02:00:00.000Z" ] }, "storyPoints": { "type": [ "number", "null" ], "description": "Story points used for agile estimation; client-supplied.", "example": 100, "examples": [ 100 ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the task in its default ordering. To reposition, send the midpoint of the two neighbours' ranks. Two subtasks under the same parent cannot share a rank.", "example": 100, "examples": [ 100 ] }, "orderList": { "type": [ "number", "null" ], "description": "Fractional rank of the task within its list. Same read/write shape and midpoint recipe as `order`.", "example": 100, "examples": [ 100 ] }, "banner": { "type": [ "string", "null" ], "description": "Cover image URL rendered at the top of the task detail view.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "embedUrl": { "type": [ "string", "null" ], "description": "External URL embedded in the task body (e.g. Loom recording, Figma frame).", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Custom-field values on this task. READ: `?expand=customFields` returns the values attached to this task. WRITE: include `customFields: [{ customFieldId, value }]` in the create/update body to set values — each one is checked against its field definition before the write commits (value is always a string; max 50 entries per request; `\"\"` clears). Field definitions live on the read-only `customField` resource.", "example": [], "examples": [ [] ] }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Team-member ids assigned to this task. On create, seeds the set. **On update, REPLACES the whole set — members you leave out are unassigned.** For additive changes use `POST`/`DELETE /tasks/{id}/assignees`. Read the current set with `?expand=assignees`.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Label ids attached to this task. On create, seeds the set. **On update, REPLACES the whole set — labels you leave out are detached.** For additive changes use `POST`/`DELETE /tasks/{id}/labels`. Read the current set with `?expand=labels`.", "example": [ "xbUMIqgS" ], "examples": [ [ "xbUMIqgS" ] ] }, "subscribers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Team-member ids subscribed to this task (they receive notifications on changes). On create, seeds the set. **On update, REPLACES the whole set — members you leave out are unsubscribed.** For additive changes use `POST`/`DELETE /tasks/{id}/subscribers`. Read the current set with `?expand=subscribers`.", "example": [ "NlUEieKe" ], "examples": [ [ "NlUEieKe" ] ] } }, "required": [ "name", "projectId" ], "additionalProperties": false }, "taskUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Task name. 1–1024 characters after trimming. Content that reads as promotional (link-farm text, bulk marketing copy) is rejected with a 400.", "example": "Example", "examples": [ "Example" ] }, "description": { "type": [ "string", "null" ], "description": "Task description. Supports Markdown formatting.", "example": "A concise description.", "examples": [ "A concise description." ] }, "archived": { "type": "boolean", "description": "Whether this resource is archived.", "example": false, "examples": [ false ] }, "completed": { "type": "boolean", "description": "Whether this task is marked complete. Set `true` to mark a task done — Nifty renders completed tasks in a virtual \"Completed\" column, so prefer this over creating a separate \"Done\" status. Pairs with `completedAt` (timestamp) and `completedById` (who completed it).", "example": false, "examples": [ false ] }, "projectId": { "type": "string", "minLength": 1, "description": "Project this task belongs to. Required on create; PATCH-ing it moves the task — and its subtasks — into another project.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "listId": { "type": [ "string", "null" ], "description": "The list this task belongs to. Null when the task is not on a list. Legal ids come from `GET /lists`.", "example": "lN6ZQycO", "examples": [ "lN6ZQycO" ] }, "statusId": { "type": [ "string", "null" ], "description": "The status column this task sits in. Null when the task has no status (e.g. a backlog item). Legal ids come from `GET /statuses`.", "example": "5aM4ncwI", "examples": [ "5aM4ncwI" ] }, "parentTaskId": { "type": [ "string", "null" ], "description": "The parent task, when this task is a subtask. Null on top-level tasks. Subtask siblings are ranked by `order`.", "example": "4KOocqYo", "examples": [ "4KOocqYo" ] }, "dependencyId": { "type": [ "string", "null" ], "description": "The single task this one waits on. Nifty models one predecessor per task, so this is an id and not an array. Null when the task has no predecessor.", "example": "i9TUmOWm", "examples": [ "i9TUmOWm" ] }, "recurringRuleId": { "type": [ "string", "null" ], "description": "The recurrence rule that regenerates this task, for recurring tasks. Null otherwise. Legal ids come from `GET /recurring-rules`.", "example": "cn2v0xiQ", "examples": [ "cn2v0xiQ" ] }, "startAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When work on this task is scheduled to start.", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this task is due.", "example": "2026-06-07T12:00:00.000Z", "examples": [ "2026-06-07T12:00:00.000Z" ] }, "remindAt": { "type": [ "string", "null" ], "format": "date-time", "description": "A single reminder time for this task. Recurring or multiple reminders are separate objects on the `reminder` resource (`GET /reminders?taskId[eq]=…`).", "example": "2026-06-04T02:00:00.000Z", "examples": [ "2026-06-04T02:00:00.000Z" ] }, "storyPoints": { "type": [ "number", "null" ], "description": "Story points used for agile estimation; client-supplied.", "example": 100, "examples": [ 100 ] }, "order": { "type": [ "number", "null" ], "description": "Fractional rank of the task in its default ordering. To reposition, send the midpoint of the two neighbours' ranks. Two subtasks under the same parent cannot share a rank.", "example": 100, "examples": [ 100 ] }, "orderList": { "type": [ "number", "null" ], "description": "Fractional rank of the task within its list. Same read/write shape and midpoint recipe as `order`.", "example": 100, "examples": [ 100 ] }, "banner": { "type": [ "string", "null" ], "description": "Cover image URL rendered at the top of the task detail view.", "example": "https://cdn.nifty.pm/example.png", "examples": [ "https://cdn.nifty.pm/example.png" ] }, "embedUrl": { "type": [ "string", "null" ], "description": "External URL embedded in the task body (e.g. Loom recording, Figma frame).", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "customFieldId": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "customFieldId", "value" ], "additionalProperties": false }, "maxItems": 50, "description": "Custom-field values on this task. READ: `?expand=customFields` returns the values attached to this task. WRITE: include `customFields: [{ customFieldId, value }]` in the create/update body to set values — each one is checked against its field definition before the write commits (value is always a string; max 50 entries per request; `\"\"` clears). Field definitions live on the read-only `customField` resource.", "example": [], "examples": [ [] ] }, "assignees": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Team-member ids assigned to this task. On create, seeds the set. **On update, REPLACES the whole set — members you leave out are unassigned.** For additive changes use `POST`/`DELETE /tasks/{id}/assignees`. Read the current set with `?expand=assignees`.", "example": [ "CNIgSuay" ], "examples": [ [ "CNIgSuay" ] ] }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Label ids attached to this task. On create, seeds the set. **On update, REPLACES the whole set — labels you leave out are detached.** For additive changes use `POST`/`DELETE /tasks/{id}/labels`. Read the current set with `?expand=labels`.", "example": [ "xbUMIqgS" ], "examples": [ [ "xbUMIqgS" ] ] }, "subscribers": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Team-member ids subscribed to this task (they receive notifications on changes). On create, seeds the set. **On update, REPLACES the whole set — members you leave out are unsubscribed.** For additive changes use `POST`/`DELETE /tasks/{id}/subscribers`. Read the current set with `?expand=subscribers`.", "example": [ "NlUEieKe" ], "examples": [ [ "NlUEieKe" ] ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "taskHandoff": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "Ef8f2Vmq", "examples": [ "Ef8f2Vmq" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "taskId": { "type": "string", "minLength": 1, "description": "Task this hand-off belongs to. Required on create; immutable afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] }, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*\\.[a-z0-9][a-z0-9-]*\\/[0-9]+$", "description": "The kind of `body`, copied from `body.schema` when the hand-off is created — filter on it to find the newest hand-off of your kind. Read-only.", "readOnly": true, "example": "nifty.checkpoint/1", "examples": [ "nifty.checkpoint/1" ] }, "summary": { "type": "string", "minLength": 1, "description": "One line a person reads on the task: what changed and what is next. Plain text, at most 500 characters, no markdown.", "example": "build → pass · next: open the PR against main", "examples": [ "build → pass · next: open the PR against main" ] }, "body": { "type": "object", "additionalProperties": {}, "description": "Working context for whoever picks this task up next — a person or an agent. JSON at most 20,000 UTF-8 bytes, no string over 10,000 characters. `body.schema` names the kind: `nifty.checkpoint/1` is validated, any other `./` is stored as-is (the `nifty.` namespace is reserved). Newest of a kind wins; never edit an old one. Put decisions WITH their reasons, checks WITH their result, and one concrete next action.", "example": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" }, "examples": [ { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } ] } }, "required": [ "id", "createdAt", "taskId", "schema", "summary", "body" ], "additionalProperties": true }, "taskHandoffExpanded": { "description": "A Handoff with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/taskHandoff" }, { "type": "object", "properties": { "task": { "allOf": [ { "$ref": "#/components/schemas/task" } ], "description": "The related Task, present only when you pass `?expand=task`.", "x-example-omit": true }, "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "taskHandoffCreate": { "type": "object", "properties": { "taskId": { "type": "string", "minLength": 1, "description": "Task this hand-off belongs to. Required on create; immutable afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ], "x-createOnly": true }, "summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "One line a person reads on the task: what changed and what is next. Plain text, at most 500 characters, no markdown.", "example": "build → pass · next: open the PR against main", "examples": [ "build → pass · next: open the PR against main" ] }, "body": { "anyOf": [ { "type": "object", "properties": { "schema": { "type": "string", "enum": [ "nifty.checkpoint/1" ] }, "requirements": { "type": "object", "properties": { "source": { "type": "string", "maxLength": 10000, "minLength": 1 }, "acceptanceCriteria": { "type": "array", "items": { "type": "string", "maxLength": 10000 }, "minItems": 1 } }, "required": [ "source", "acceptanceCriteria" ], "additionalProperties": false }, "invariantRegister": { "type": "array", "items": { "type": "string", "maxLength": 10000 } }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "decision": { "type": "string", "maxLength": 10000, "minLength": 1 }, "reason": { "type": "string", "maxLength": 10000, "minLength": 1 } }, "required": [ "decision", "reason" ], "additionalProperties": false } }, "hypothesesEvaluated": { "type": "array", "items": { "type": "object", "properties": { "idea": { "type": "string", "maxLength": 10000, "minLength": 1 }, "result": { "type": "string", "maxLength": 10000, "minLength": 1 } }, "required": [ "idea", "result" ], "additionalProperties": false } }, "deltaState": { "type": "object", "properties": { "filesModified": { "type": "array", "items": { "type": "string", "maxLength": 10000 } }, "checksRun": { "type": "array", "items": { "type": "object", "properties": { "cmd": { "type": "string", "maxLength": 10000, "minLength": 1 }, "revision": { "type": "string", "maxLength": 10000, "minLength": 1 }, "result": { "type": "string", "maxLength": 10000, "minLength": 1 }, "stackTrace": { "type": "string", "maxLength": 10000 } }, "required": [ "cmd", "revision", "result" ], "additionalProperties": false } } }, "required": [ "filesModified", "checksRun" ], "additionalProperties": false }, "openQuestions": { "type": "array", "items": { "type": "string", "maxLength": 10000 } }, "executionPointer": { "type": "object", "properties": { "nextAction": { "type": "string", "maxLength": 10000, "minLength": 1 }, "blockedBy": { "type": [ "string", "null" ], "maxLength": 10000 } }, "required": [ "nextAction", "blockedBy" ], "additionalProperties": false }, "repos": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 10000, "minLength": 1 }, "sha": { "type": "string", "maxLength": 10000, "minLength": 1 }, "branch": { "type": "string", "maxLength": 10000, "minLength": 1 }, "pushed": { "type": "boolean" }, "dirty": { "type": "boolean" } }, "required": [ "name", "sha", "branch", "pushed", "dirty" ], "additionalProperties": false } }, "writer": { "type": "object", "properties": { "tool": { "type": "string", "maxLength": 10000, "minLength": 1 }, "model": { "type": "string", "maxLength": 10000 }, "sessionId": { "type": "string", "maxLength": 10000 } }, "required": [ "tool" ], "additionalProperties": false }, "precededBy": { "type": [ "string", "null" ], "maxLength": 10000 }, "truncatedFields": { "type": "array", "items": { "type": "string", "maxLength": 10000 } }, "mirrorSkipped": { "type": "array", "items": { "type": "object", "properties": { "rung": { "type": "string", "maxLength": 10000, "minLength": 1 }, "reason": { "type": "string", "maxLength": 10000, "minLength": 1 } }, "required": [ "rung", "reason" ], "additionalProperties": false } } }, "required": [ "schema", "requirements", "invariantRegister", "decisions", "hypothesesEvaluated", "deltaState", "openQuestions", "executionPointer", "repos", "writer", "precededBy" ], "additionalProperties": false }, { "type": "object", "properties": { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*\\.[a-z0-9][a-z0-9-]*\\/[0-9]+$" } }, "required": [ "schema" ], "additionalProperties": true } ], "description": "Working context for whoever picks this task up next — a person or an agent. JSON at most 20,000 UTF-8 bytes, no string over 10,000 characters. `body.schema` names the kind: `nifty.checkpoint/1` is validated, any other `./` is stored as-is (the `nifty.` namespace is reserved). Newest of a kind wins; never edit an old one. Put decisions WITH their reasons, checks WITH their result, and one concrete next action.", "example": { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" }, "examples": [ { "schema": "nifty.checkpoint/1", "requirements": { "source": "card description", "acceptanceCriteria": [ "the export downloads as CSV" ] }, "invariantRegister": [ "never write to the production replica" ], "decisions": [ { "decision": "stream the CSV instead of buffering it", "reason": "exports above 50k rows ran out of memory" } ], "hypothesesEvaluated": [ { "idea": "raise the worker memory limit", "result": "rejected — hides the bug at 100k rows" } ], "deltaState": { "filesModified": [ "src/export/csv.service.ts" ], "checksRun": [ { "cmd": "npm test -- csv", "revision": "a1b2c3d", "result": "12 passed" } ] }, "openQuestions": [ "should the export include archived rows?" ], "executionPointer": { "nextAction": "open the PR and request review", "blockedBy": "the streaming change must merge first" }, "repos": [ { "name": "api", "sha": "a1b2c3d", "branch": "feat/csv-export", "pushed": true, "dirty": false } ], "writer": { "tool": "claude-code" }, "precededBy": "thNfB2k9" } ] } }, "required": [ "taskId", "summary", "body" ], "additionalProperties": false }, "timeEntry": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource.", "readOnly": true, "example": "sfmueIsa", "examples": [ "sfmueIsa" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "description": { "type": [ "string", "null" ], "description": "Free-text note about what the time was spent on. This is the field `GET /time-entries/search` matches against.", "example": "A concise description.", "examples": [ "A concise description." ] }, "start": { "type": "string", "format": "date-time", "description": "When the tracked interval began (ISO 8601).", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tracked interval ended (ISO 8601). Omit it, or send null, to create a running entry; PATCH `end` to stop it.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "manual": { "type": "boolean", "description": "True for entries created through this API; false for entries captured by the timer in the Nifty app. Server-set.", "readOnly": true, "example": false, "examples": [ false ] }, "projectId": { "type": [ "string", "null" ], "description": "The project this time is booked against. Set once when the entry is created: an entry cannot be moved to another project afterwards.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ] }, "memberId": { "type": "string", "minLength": 1, "description": "The team member this time is tracked for. Set by the server from whoever is calling — you cannot log time on someone else's behalf.", "readOnly": true, "example": "P3hYIKqK", "examples": [ "P3hYIKqK" ] }, "taskId": { "type": "string", "minLength": 1, "description": "The task this time is tracked against. Set once when the entry is created: an entry cannot be moved to another task afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ] } }, "required": [ "id", "createdAt", "start", "manual", "memberId", "taskId" ], "additionalProperties": true }, "timeEntryExpanded": { "description": "A Time Entry with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/timeEntry" }, { "type": "object", "properties": { "member": { "allOf": [ { "$ref": "#/components/schemas/member" } ], "description": "The related Team Member, present only when you pass `?expand=member`.", "x-example-omit": true } } } ] }, "timeEntryCreate": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "description": "Free-text note about what the time was spent on. This is the field `GET /time-entries/search` matches against.", "example": "A concise description.", "examples": [ "A concise description." ] }, "start": { "type": "string", "format": "date-time", "description": "When the tracked interval began (ISO 8601).", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tracked interval ended (ISO 8601). Omit it, or send null, to create a running entry; PATCH `end` to stop it.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "projectId": { "type": [ "string", "null" ], "description": "The project this time is booked against. Set once when the entry is created: an entry cannot be moved to another project afterwards.", "example": "iV6vIU8N", "examples": [ "iV6vIU8N" ], "x-createOnly": true }, "taskId": { "type": "string", "minLength": 1, "description": "The task this time is tracked against. Set once when the entry is created: an entry cannot be moved to another task afterwards.", "example": "KfS0ha8P", "examples": [ "KfS0ha8P" ], "x-createOnly": true } }, "required": [ "start", "taskId" ], "additionalProperties": false }, "timeEntryUpdate": { "type": "object", "properties": { "description": { "type": [ "string", "null" ], "description": "Free-text note about what the time was spent on. This is the field `GET /time-entries/search` matches against.", "example": "A concise description.", "examples": [ "A concise description." ] }, "start": { "type": "string", "format": "date-time", "description": "When the tracked interval began (ISO 8601).", "example": "2026-06-01T12:00:00.000Z", "examples": [ "2026-06-01T12:00:00.000Z" ] }, "end": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tracked interval ended (ISO 8601). Omit it, or send null, to create a running entry; PATCH `end` to stop it.", "example": "2026-06-14T12:00:00.000Z", "examples": [ "2026-06-14T12:00:00.000Z" ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false }, "webhook": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier. Server-minted, stable, opaque.", "readOnly": true, "example": "GZiSa6Jk", "examples": [ "GZiSa6Jk" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Team member who deleted this webhook. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "ej4HwmyI", "examples": [ "ej4HwmyI" ] }, "name": { "type": "string", "minLength": 1, "description": "Human-readable label for this endpoint, shown in the integrations UI.", "example": "Example", "examples": [ "Example" ] }, "url": { "type": "string", "minLength": 1, "description": "The HTTPS endpoint each matching event is POSTed to.\n\n**Verifying a delivery.** Every request carries an `X-Webhook-Signature` header of the form `t=,v1=`, where the hex is an HMAC-SHA256 of `${t}.${rawBody}` keyed with this webhook's secret. Reject a request whose `t` is more than **300 seconds** away from your own clock — that window is what stops a captured request being replayed at you.\n\n**Delivery semantics.** Each event is attempted up to **4 times** (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (`active` flips to false) and you will have to re-enable it; any success resets that counter and updates `lastDeliveredAt`. Send `POST /webhooks/{id}/test` to fire a synthetic delivery at your endpoint before going live.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "x-known-values": [ "annotation.created", "annotation.force_deleted", "annotation.removed", "annotation.restored", "annotation.updated", "chat.created", "chat.force_deleted", "chat.removed", "chat.restored", "chat.updated", "checkIn.assignees.added", "checkIn.assignees.removed", "checkIn.created", "checkIn.force_deleted", "checkIn.removed", "checkIn.restored", "checkIn.subscribers.added", "checkIn.subscribers.removed", "checkIn.updated", "checkInRequest.assignees.added", "checkInRequest.assignees.removed", "checkInRequest.created", "checkInRequest.force_deleted", "checkInRequest.removed", "checkInRequest.restored", "checkInRequest.updated", "checklist.created", "checklist.force_deleted", "checklist.removed", "checklist.restored", "checklist.updated", "checklistItem.created", "checklistItem.force_deleted", "checklistItem.removed", "checklistItem.restored", "checklistItem.updated", "document.append", "document.created", "document.editText", "document.force_deleted", "document.labels.added", "document.labels.removed", "document.removed", "document.restored", "document.updated", "favorite.created", "favorite.force_deleted", "favorite.removed", "favorite.restored", "favorite.updated", "favoriteFolder.created", "favoriteFolder.force_deleted", "favoriteFolder.removed", "favoriteFolder.restored", "favoriteFolder.updated", "file.createFromContent", "file.createUploadUrl", "file.created", "file.force_deleted", "file.labels.added", "file.labels.removed", "file.removed", "file.restored", "file.subscribers.added", "file.subscribers.removed", "file.updated", "file.uploadFromUrl", "form.created", "form.force_deleted", "form.removed", "form.restored", "form.updated", "goal.created", "goal.force_deleted", "goal.removed", "goal.restored", "goal.updated", "goalGroup.created", "goalGroup.force_deleted", "goalGroup.removed", "goalGroup.restored", "goalGroup.updated", "label.created", "label.force_deleted", "label.removed", "label.restored", "label.updated", "list.assignees.added", "list.assignees.removed", "list.created", "list.force_deleted", "list.goals.added", "list.goals.removed", "list.hiddenFor.added", "list.hiddenFor.removed", "list.removed", "list.restored", "list.updated", "member.created", "member.force_deleted", "member.removed", "member.restored", "member.updated", "message.created", "message.force_deleted", "message.removed", "message.restored", "message.updated", "portfolio.created", "portfolio.force_deleted", "portfolio.members.added", "portfolio.members.removed", "portfolio.removed", "portfolio.restored", "portfolio.updated", "presenceStatus.created", "presenceStatus.force_deleted", "presenceStatus.removed", "presenceStatus.restored", "presenceStatus.updated", "project.created", "project.force_deleted", "project.members.added", "project.members.removed", "project.removed", "project.restored", "project.transfer", "project.updated", "projectDashboard.created", "projectDashboard.force_deleted", "projectDashboard.removed", "projectDashboard.restored", "projectDashboard.updated", "projectFolder.created", "projectFolder.force_deleted", "projectFolder.removed", "projectFolder.restored", "projectFolder.updated", "recurringRule.created", "recurringRule.force_deleted", "recurringRule.removed", "recurringRule.restored", "recurringRule.updated", "reminder.created", "reminder.force_deleted", "reminder.removed", "reminder.restored", "reminder.updated", "reportChart.created", "reportChart.force_deleted", "reportChart.projects.added", "reportChart.projects.removed", "reportChart.removed", "reportChart.restored", "reportChart.updated", "role.created", "role.force_deleted", "role.removed", "role.restored", "role.updated", "status.assignees.added", "status.assignees.removed", "status.created", "status.force_deleted", "status.hiddenFor.added", "status.hiddenFor.removed", "status.removed", "status.restored", "status.updated", "task.assignees.added", "task.assignees.removed", "task.attachDocument", "task.connectedTasks.added", "task.connectedTasks.removed", "task.createTree", "task.created", "task.detachDocument", "task.force_deleted", "task.hiddenFor.added", "task.hiddenFor.removed", "task.labels.added", "task.labels.removed", "task.removed", "task.restored", "task.subscribers.added", "task.subscribers.removed", "task.updated", "taskHandoff.created", "taskHandoff.force_deleted", "taskHandoff.removed", "taskHandoff.restored", "taskHandoff.updated", "timeEntry.created", "timeEntry.force_deleted", "timeEntry.removed", "timeEntry.restored", "timeEntry.updated", "webhook.created", "webhook.force_deleted", "webhook.removed", "webhook.restored", "webhook.rotateSecret", "webhook.test", "webhook.updated" ] }, "description": "Which events this webhook receives.\n\n**Grammar.** An entry is either an exact event name such as `task.created`, or a pattern. In a pattern each `*` stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so `task.*` matches `task.created` and `task.updated` but NOT the three-segment `task.assignees.added`; reach those with `task.*.*`, or by exact name. The bare `*` is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the [event catalog](https://developers.niftypm.com/docs/webhooks#event-catalog) is rejected at registration, so subscribe using the values listed below.\n\n**Lifecycle events.** Each resource below emits all five of `created`, `updated`, `removed`, `restored` and `force_deleted`, as `{resource}.{action}`:\n\n`annotation`, `chat`, `checkIn`, `checkInRequest`, `checklist`, `checklistItem`, `document`, `favorite`, `favoriteFolder`, `file`, `form`, `goal`, `goalGroup`, `label`, `list`, `member`, `message`, `portfolio`, `project`, `projectDashboard`, `projectFolder`, `recurringRule`, `reminder`, `reportChart`, `role`, `status`, `task`, `taskHandoff`, `presenceStatus`, `timeEntry`, `webhook`.\n\n**Membership events.** `{resource}.{relation}.added` and `{resource}.{relation}.removed` fire when a link is made or broken — one pair per relation listed here:\n\n- `checkIn` — `assignees`, `subscribers`\n- `checkInRequest` — `assignees`\n- `file` — `labels`, `subscribers`\n- `list` — `assignees`, `goals`, `hiddenFor`\n- `portfolio` — `members`\n- `reportChart` — `projects`\n- `status` — `assignees`, `hiddenFor`\n- `task` — `assignees`, `connectedTasks`, `hiddenFor`, `labels`, `subscribers`\n\n**Operation events.** Each named operation emits an event of the same name — the verb, not a past tense: `document.append`, `document.editText`, `file.createFromContent`, `file.createUploadUrl`, `file.uploadFromUrl`, `project.addMember`, `project.removeMember`, `project.transfer`, `task.attachDocument`, `task.createTree`, `task.detachDocument`, `webhook.rotateSecret`, `webhook.test`.", "example": [ "task.created", "task.updated", "project.*" ], "examples": [ [ "task.created", "task.updated", "project.*" ] ] }, "apiVersion": { "type": "string", "enum": [ "latest", "2026-03-20" ], "description": "Which payload format your endpoint receives, echoed back to you as the `X-Api-Version` request header. `latest` follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to `latest`.", "example": "latest", "examples": [ "latest" ] }, "active": { "type": "boolean", "description": "Whether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.", "example": true, "examples": [ true ] }, "createdById": { "type": [ "string", "null" ], "minLength": 1, "description": "Team member who registered this webhook. Server-set from the caller identity; a member id, so resolve it with `GET /members/{id}`.", "readOnly": true, "example": "rBIGEQCa", "examples": [ "rBIGEQCa" ] }, "lastDeliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery to this endpoint last succeeded. null if it has never delivered.", "readOnly": true, "example": "2026-06-06T03:00:00.000Z", "examples": [ "2026-06-06T03:00:00.000Z" ] }, "failCount": { "type": "integer", "description": "Consecutive delivery failures. Reset to 0 on any success; at 10 the webhook is automatically deactivated.", "readOnly": true, "example": 0, "examples": [ 0 ] } }, "required": [ "id", "createdAt", "name", "url", "events", "apiVersion", "active", "failCount" ], "additionalProperties": false }, "webhookExpanded": { "description": "A Webhook with its `?expand=` relations inlined.", "allOf": [ { "$ref": "#/components/schemas/webhook" }, { "type": "object", "properties": { "createdByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=createdByActor`.", "x-example-omit": true }, "updatedByActor": { "allOf": [ { "$ref": "#/components/schemas/actor" } ], "description": "The related Actor, present only when you pass `?expand=updatedByActor`.", "x-example-omit": true } } } ] }, "webhookCreated": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier. Server-minted, stable, opaque.", "readOnly": true, "example": "GZiSa6Jk", "examples": [ "GZiSa6Jk" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "readOnly": true, "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp.", "readOnly": true, "example": "2026-05-31T14:00:00.000Z", "examples": [ "2026-05-31T14:00:00.000Z" ] }, "createdByActorId": { "type": [ "string", "null" ], "description": "Who created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "49f861f7-4af8-44bf-844f-45f85babe504", "examples": [ "49f861f7-4af8-44bf-844f-45f85babe504" ] }, "updatedByActorId": { "type": [ "string", "null" ], "description": "Who last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with `GET /actors/{id}`, whose `memberId` gives you the person to use against `/members`.", "readOnly": true, "example": "3306ed14-3606-4350-8300-2f06e6c80dce", "examples": [ "3306ed14-3606-4350-8300-2f06e6c80dce" ] }, "createdByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "updatedByActorType": { "type": [ "string", "null" ], "enum": [ "human", "agent", "cron", "recurringTask", "automation", "outboxRetry", "systemDefault" ], "description": "The last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from `actors.type` via the row's `updatedByActorId`; read-only, not directly writable.", "readOnly": true, "example": "human", "examples": [ "human" ] }, "purgeAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.", "readOnly": true, "example": "2026-06-30T12:00:00.000Z", "examples": [ "2026-06-30T12:00:00.000Z" ] }, "deletedById": { "type": [ "string", "null" ], "description": "Team member who deleted this webhook. A member id — resolve it with `GET /members/{id}`.", "readOnly": true, "example": "ej4HwmyI", "examples": [ "ej4HwmyI" ] }, "name": { "type": "string", "minLength": 1, "description": "Human-readable label for this endpoint, shown in the integrations UI.", "example": "Example", "examples": [ "Example" ] }, "url": { "type": "string", "minLength": 1, "description": "The HTTPS endpoint each matching event is POSTed to.\n\n**Verifying a delivery.** Every request carries an `X-Webhook-Signature` header of the form `t=,v1=`, where the hex is an HMAC-SHA256 of `${t}.${rawBody}` keyed with this webhook's secret. Reject a request whose `t` is more than **300 seconds** away from your own clock — that window is what stops a captured request being replayed at you.\n\n**Delivery semantics.** Each event is attempted up to **4 times** (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (`active` flips to false) and you will have to re-enable it; any success resets that counter and updates `lastDeliveredAt`. Send `POST /webhooks/{id}/test` to fire a synthetic delivery at your endpoint before going live.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "x-known-values": [ "annotation.created", "annotation.force_deleted", "annotation.removed", "annotation.restored", "annotation.updated", "chat.created", "chat.force_deleted", "chat.removed", "chat.restored", "chat.updated", "checkIn.assignees.added", "checkIn.assignees.removed", "checkIn.created", "checkIn.force_deleted", "checkIn.removed", "checkIn.restored", "checkIn.subscribers.added", "checkIn.subscribers.removed", "checkIn.updated", "checkInRequest.assignees.added", "checkInRequest.assignees.removed", "checkInRequest.created", "checkInRequest.force_deleted", "checkInRequest.removed", "checkInRequest.restored", "checkInRequest.updated", "checklist.created", "checklist.force_deleted", "checklist.removed", "checklist.restored", "checklist.updated", "checklistItem.created", "checklistItem.force_deleted", "checklistItem.removed", "checklistItem.restored", "checklistItem.updated", "document.append", "document.created", "document.editText", "document.force_deleted", "document.labels.added", "document.labels.removed", "document.removed", "document.restored", "document.updated", "favorite.created", "favorite.force_deleted", "favorite.removed", "favorite.restored", "favorite.updated", "favoriteFolder.created", "favoriteFolder.force_deleted", "favoriteFolder.removed", "favoriteFolder.restored", "favoriteFolder.updated", "file.createFromContent", "file.createUploadUrl", "file.created", "file.force_deleted", "file.labels.added", "file.labels.removed", "file.removed", "file.restored", "file.subscribers.added", "file.subscribers.removed", "file.updated", "file.uploadFromUrl", "form.created", "form.force_deleted", "form.removed", "form.restored", "form.updated", "goal.created", "goal.force_deleted", "goal.removed", "goal.restored", "goal.updated", "goalGroup.created", "goalGroup.force_deleted", "goalGroup.removed", "goalGroup.restored", "goalGroup.updated", "label.created", "label.force_deleted", "label.removed", "label.restored", "label.updated", "list.assignees.added", "list.assignees.removed", "list.created", "list.force_deleted", "list.goals.added", "list.goals.removed", "list.hiddenFor.added", "list.hiddenFor.removed", "list.removed", "list.restored", "list.updated", "member.created", "member.force_deleted", "member.removed", "member.restored", "member.updated", "message.created", "message.force_deleted", "message.removed", "message.restored", "message.updated", "portfolio.created", "portfolio.force_deleted", "portfolio.members.added", "portfolio.members.removed", "portfolio.removed", "portfolio.restored", "portfolio.updated", "presenceStatus.created", "presenceStatus.force_deleted", "presenceStatus.removed", "presenceStatus.restored", "presenceStatus.updated", "project.created", "project.force_deleted", "project.members.added", "project.members.removed", "project.removed", "project.restored", "project.transfer", "project.updated", "projectDashboard.created", "projectDashboard.force_deleted", "projectDashboard.removed", "projectDashboard.restored", "projectDashboard.updated", "projectFolder.created", "projectFolder.force_deleted", "projectFolder.removed", "projectFolder.restored", "projectFolder.updated", "recurringRule.created", "recurringRule.force_deleted", "recurringRule.removed", "recurringRule.restored", "recurringRule.updated", "reminder.created", "reminder.force_deleted", "reminder.removed", "reminder.restored", "reminder.updated", "reportChart.created", "reportChart.force_deleted", "reportChart.projects.added", "reportChart.projects.removed", "reportChart.removed", "reportChart.restored", "reportChart.updated", "role.created", "role.force_deleted", "role.removed", "role.restored", "role.updated", "status.assignees.added", "status.assignees.removed", "status.created", "status.force_deleted", "status.hiddenFor.added", "status.hiddenFor.removed", "status.removed", "status.restored", "status.updated", "task.assignees.added", "task.assignees.removed", "task.attachDocument", "task.connectedTasks.added", "task.connectedTasks.removed", "task.createTree", "task.created", "task.detachDocument", "task.force_deleted", "task.hiddenFor.added", "task.hiddenFor.removed", "task.labels.added", "task.labels.removed", "task.removed", "task.restored", "task.subscribers.added", "task.subscribers.removed", "task.updated", "taskHandoff.created", "taskHandoff.force_deleted", "taskHandoff.removed", "taskHandoff.restored", "taskHandoff.updated", "timeEntry.created", "timeEntry.force_deleted", "timeEntry.removed", "timeEntry.restored", "timeEntry.updated", "webhook.created", "webhook.force_deleted", "webhook.removed", "webhook.restored", "webhook.rotateSecret", "webhook.test", "webhook.updated" ] }, "description": "Which events this webhook receives.\n\n**Grammar.** An entry is either an exact event name such as `task.created`, or a pattern. In a pattern each `*` stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so `task.*` matches `task.created` and `task.updated` but NOT the three-segment `task.assignees.added`; reach those with `task.*.*`, or by exact name. The bare `*` is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the [event catalog](https://developers.niftypm.com/docs/webhooks#event-catalog) is rejected at registration, so subscribe using the values listed below.\n\n**Lifecycle events.** Each resource below emits all five of `created`, `updated`, `removed`, `restored` and `force_deleted`, as `{resource}.{action}`:\n\n`annotation`, `chat`, `checkIn`, `checkInRequest`, `checklist`, `checklistItem`, `document`, `favorite`, `favoriteFolder`, `file`, `form`, `goal`, `goalGroup`, `label`, `list`, `member`, `message`, `portfolio`, `project`, `projectDashboard`, `projectFolder`, `recurringRule`, `reminder`, `reportChart`, `role`, `status`, `task`, `taskHandoff`, `presenceStatus`, `timeEntry`, `webhook`.\n\n**Membership events.** `{resource}.{relation}.added` and `{resource}.{relation}.removed` fire when a link is made or broken — one pair per relation listed here:\n\n- `checkIn` — `assignees`, `subscribers`\n- `checkInRequest` — `assignees`\n- `file` — `labels`, `subscribers`\n- `list` — `assignees`, `goals`, `hiddenFor`\n- `portfolio` — `members`\n- `reportChart` — `projects`\n- `status` — `assignees`, `hiddenFor`\n- `task` — `assignees`, `connectedTasks`, `hiddenFor`, `labels`, `subscribers`\n\n**Operation events.** Each named operation emits an event of the same name — the verb, not a past tense: `document.append`, `document.editText`, `file.createFromContent`, `file.createUploadUrl`, `file.uploadFromUrl`, `project.addMember`, `project.removeMember`, `project.transfer`, `task.attachDocument`, `task.createTree`, `task.detachDocument`, `webhook.rotateSecret`, `webhook.test`.", "example": [ "task.created", "task.updated", "project.*" ], "examples": [ [ "task.created", "task.updated", "project.*" ] ] }, "apiVersion": { "type": "string", "enum": [ "latest", "2026-03-20" ], "description": "Which payload format your endpoint receives, echoed back to you as the `X-Api-Version` request header. `latest` follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to `latest`.", "example": "latest", "examples": [ "latest" ] }, "active": { "type": "boolean", "description": "Whether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.", "example": true, "examples": [ true ] }, "createdById": { "type": [ "string", "null" ], "minLength": 1, "description": "Team member who registered this webhook. Server-set from the caller identity; a member id, so resolve it with `GET /members/{id}`.", "readOnly": true, "example": "rBIGEQCa", "examples": [ "rBIGEQCa" ] }, "lastDeliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery to this endpoint last succeeded. null if it has never delivered.", "readOnly": true, "example": "2026-06-06T03:00:00.000Z", "examples": [ "2026-06-06T03:00:00.000Z" ] }, "failCount": { "type": "integer", "description": "Consecutive delivery failures. Reset to 0 on any success; at 10 the webhook is automatically deactivated.", "readOnly": true, "example": 0, "examples": [ 0 ] }, "secret": { "type": "string", "minLength": 1, "description": "The signing secret for this webhook, in plaintext. **Returned exactly once** — here, and again from `POST /webhooks/{id}/rotate-secret` — and never readable afterwards, so store it before you do anything else. Use it to verify the `X-Webhook-Signature` header on every delivery. If you lose it, rotate: `POST /webhooks/{id}/rotate-secret` mints a new one and invalidates the old. NOTE: replaying this exact request with the same `Idempotency-Key` returns the body WITHOUT `secret` — once means once.", "example": "Example secret", "examples": [ "Example secret" ] } }, "required": [ "id", "createdAt", "name", "url", "events", "apiVersion", "active", "failCount", "secret" ], "additionalProperties": false }, "webhookCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable label for this endpoint, shown in the integrations UI.", "example": "Example", "examples": [ "Example" ] }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/", "description": "The HTTPS endpoint each matching event is POSTed to.\n\n**Verifying a delivery.** Every request carries an `X-Webhook-Signature` header of the form `t=,v1=`, where the hex is an HMAC-SHA256 of `${t}.${rawBody}` keyed with this webhook's secret. Reject a request whose `t` is more than **300 seconds** away from your own clock — that window is what stops a captured request being replayed at you.\n\n**Delivery semantics.** Each event is attempted up to **4 times** (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (`active` flips to false) and you will have to re-enable it; any success resets that counter and updates `lastDeliveredAt`. Send `POST /webhooks/{id}/test` to fire a synthetic delivery at your endpoint before going live.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "x-known-values": [ "annotation.created", "annotation.force_deleted", "annotation.removed", "annotation.restored", "annotation.updated", "chat.created", "chat.force_deleted", "chat.removed", "chat.restored", "chat.updated", "checkIn.assignees.added", "checkIn.assignees.removed", "checkIn.created", "checkIn.force_deleted", "checkIn.removed", "checkIn.restored", "checkIn.subscribers.added", "checkIn.subscribers.removed", "checkIn.updated", "checkInRequest.assignees.added", "checkInRequest.assignees.removed", "checkInRequest.created", "checkInRequest.force_deleted", "checkInRequest.removed", "checkInRequest.restored", "checkInRequest.updated", "checklist.created", "checklist.force_deleted", "checklist.removed", "checklist.restored", "checklist.updated", "checklistItem.created", "checklistItem.force_deleted", "checklistItem.removed", "checklistItem.restored", "checklistItem.updated", "document.append", "document.created", "document.editText", "document.force_deleted", "document.labels.added", "document.labels.removed", "document.removed", "document.restored", "document.updated", "favorite.created", "favorite.force_deleted", "favorite.removed", "favorite.restored", "favorite.updated", "favoriteFolder.created", "favoriteFolder.force_deleted", "favoriteFolder.removed", "favoriteFolder.restored", "favoriteFolder.updated", "file.createFromContent", "file.createUploadUrl", "file.created", "file.force_deleted", "file.labels.added", "file.labels.removed", "file.removed", "file.restored", "file.subscribers.added", "file.subscribers.removed", "file.updated", "file.uploadFromUrl", "form.created", "form.force_deleted", "form.removed", "form.restored", "form.updated", "goal.created", "goal.force_deleted", "goal.removed", "goal.restored", "goal.updated", "goalGroup.created", "goalGroup.force_deleted", "goalGroup.removed", "goalGroup.restored", "goalGroup.updated", "label.created", "label.force_deleted", "label.removed", "label.restored", "label.updated", "list.assignees.added", "list.assignees.removed", "list.created", "list.force_deleted", "list.goals.added", "list.goals.removed", "list.hiddenFor.added", "list.hiddenFor.removed", "list.removed", "list.restored", "list.updated", "member.created", "member.force_deleted", "member.removed", "member.restored", "member.updated", "message.created", "message.force_deleted", "message.removed", "message.restored", "message.updated", "portfolio.created", "portfolio.force_deleted", "portfolio.members.added", "portfolio.members.removed", "portfolio.removed", "portfolio.restored", "portfolio.updated", "presenceStatus.created", "presenceStatus.force_deleted", "presenceStatus.removed", "presenceStatus.restored", "presenceStatus.updated", "project.created", "project.force_deleted", "project.members.added", "project.members.removed", "project.removed", "project.restored", "project.transfer", "project.updated", "projectDashboard.created", "projectDashboard.force_deleted", "projectDashboard.removed", "projectDashboard.restored", "projectDashboard.updated", "projectFolder.created", "projectFolder.force_deleted", "projectFolder.removed", "projectFolder.restored", "projectFolder.updated", "recurringRule.created", "recurringRule.force_deleted", "recurringRule.removed", "recurringRule.restored", "recurringRule.updated", "reminder.created", "reminder.force_deleted", "reminder.removed", "reminder.restored", "reminder.updated", "reportChart.created", "reportChart.force_deleted", "reportChart.projects.added", "reportChart.projects.removed", "reportChart.removed", "reportChart.restored", "reportChart.updated", "role.created", "role.force_deleted", "role.removed", "role.restored", "role.updated", "status.assignees.added", "status.assignees.removed", "status.created", "status.force_deleted", "status.hiddenFor.added", "status.hiddenFor.removed", "status.removed", "status.restored", "status.updated", "task.assignees.added", "task.assignees.removed", "task.attachDocument", "task.connectedTasks.added", "task.connectedTasks.removed", "task.createTree", "task.created", "task.detachDocument", "task.force_deleted", "task.hiddenFor.added", "task.hiddenFor.removed", "task.labels.added", "task.labels.removed", "task.removed", "task.restored", "task.subscribers.added", "task.subscribers.removed", "task.updated", "taskHandoff.created", "taskHandoff.force_deleted", "taskHandoff.removed", "taskHandoff.restored", "taskHandoff.updated", "timeEntry.created", "timeEntry.force_deleted", "timeEntry.removed", "timeEntry.restored", "timeEntry.updated", "webhook.created", "webhook.force_deleted", "webhook.removed", "webhook.restored", "webhook.rotateSecret", "webhook.test", "webhook.updated" ] }, "minItems": 1, "maxItems": 100, "description": "Which events this webhook receives.\n\n**Grammar.** An entry is either an exact event name such as `task.created`, or a pattern. In a pattern each `*` stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so `task.*` matches `task.created` and `task.updated` but NOT the three-segment `task.assignees.added`; reach those with `task.*.*`, or by exact name. The bare `*` is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the [event catalog](https://developers.niftypm.com/docs/webhooks#event-catalog) is rejected at registration, so subscribe using the values listed below.\n\n**Lifecycle events.** Each resource below emits all five of `created`, `updated`, `removed`, `restored` and `force_deleted`, as `{resource}.{action}`:\n\n`annotation`, `chat`, `checkIn`, `checkInRequest`, `checklist`, `checklistItem`, `document`, `favorite`, `favoriteFolder`, `file`, `form`, `goal`, `goalGroup`, `label`, `list`, `member`, `message`, `portfolio`, `project`, `projectDashboard`, `projectFolder`, `recurringRule`, `reminder`, `reportChart`, `role`, `status`, `task`, `taskHandoff`, `presenceStatus`, `timeEntry`, `webhook`.\n\n**Membership events.** `{resource}.{relation}.added` and `{resource}.{relation}.removed` fire when a link is made or broken — one pair per relation listed here:\n\n- `checkIn` — `assignees`, `subscribers`\n- `checkInRequest` — `assignees`\n- `file` — `labels`, `subscribers`\n- `list` — `assignees`, `goals`, `hiddenFor`\n- `portfolio` — `members`\n- `reportChart` — `projects`\n- `status` — `assignees`, `hiddenFor`\n- `task` — `assignees`, `connectedTasks`, `hiddenFor`, `labels`, `subscribers`\n\n**Operation events.** Each named operation emits an event of the same name — the verb, not a past tense: `document.append`, `document.editText`, `file.createFromContent`, `file.createUploadUrl`, `file.uploadFromUrl`, `project.addMember`, `project.removeMember`, `project.transfer`, `task.attachDocument`, `task.createTree`, `task.detachDocument`, `webhook.rotateSecret`, `webhook.test`.", "example": [ "task.created", "task.updated", "project.*" ], "examples": [ [ "task.created", "task.updated", "project.*" ] ] }, "apiVersion": { "type": "string", "enum": [ "latest", "2026-03-20" ], "description": "Which payload format your endpoint receives, echoed back to you as the `X-Api-Version` request header. `latest` follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to `latest`.", "example": "latest", "examples": [ "latest" ] }, "active": { "type": "boolean", "description": "Whether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.", "example": true, "examples": [ true ] } }, "required": [ "name", "url", "events" ], "additionalProperties": false }, "webhookUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable label for this endpoint, shown in the integrations UI.", "example": "Example", "examples": [ "Example" ] }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/", "description": "The HTTPS endpoint each matching event is POSTed to.\n\n**Verifying a delivery.** Every request carries an `X-Webhook-Signature` header of the form `t=,v1=`, where the hex is an HMAC-SHA256 of `${t}.${rawBody}` keyed with this webhook's secret. Reject a request whose `t` is more than **300 seconds** away from your own clock — that window is what stops a captured request being replayed at you.\n\n**Delivery semantics.** Each event is attempted up to **4 times** (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (`active` flips to false) and you will have to re-enable it; any success resets that counter and updates `lastDeliveredAt`. Send `POST /webhooks/{id}/test` to fire a synthetic delivery at your endpoint before going live.", "example": "https://example.com/resource", "examples": [ "https://example.com/resource" ] }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128, "x-known-values": [ "annotation.created", "annotation.force_deleted", "annotation.removed", "annotation.restored", "annotation.updated", "chat.created", "chat.force_deleted", "chat.removed", "chat.restored", "chat.updated", "checkIn.assignees.added", "checkIn.assignees.removed", "checkIn.created", "checkIn.force_deleted", "checkIn.removed", "checkIn.restored", "checkIn.subscribers.added", "checkIn.subscribers.removed", "checkIn.updated", "checkInRequest.assignees.added", "checkInRequest.assignees.removed", "checkInRequest.created", "checkInRequest.force_deleted", "checkInRequest.removed", "checkInRequest.restored", "checkInRequest.updated", "checklist.created", "checklist.force_deleted", "checklist.removed", "checklist.restored", "checklist.updated", "checklistItem.created", "checklistItem.force_deleted", "checklistItem.removed", "checklistItem.restored", "checklistItem.updated", "document.append", "document.created", "document.editText", "document.force_deleted", "document.labels.added", "document.labels.removed", "document.removed", "document.restored", "document.updated", "favorite.created", "favorite.force_deleted", "favorite.removed", "favorite.restored", "favorite.updated", "favoriteFolder.created", "favoriteFolder.force_deleted", "favoriteFolder.removed", "favoriteFolder.restored", "favoriteFolder.updated", "file.createFromContent", "file.createUploadUrl", "file.created", "file.force_deleted", "file.labels.added", "file.labels.removed", "file.removed", "file.restored", "file.subscribers.added", "file.subscribers.removed", "file.updated", "file.uploadFromUrl", "form.created", "form.force_deleted", "form.removed", "form.restored", "form.updated", "goal.created", "goal.force_deleted", "goal.removed", "goal.restored", "goal.updated", "goalGroup.created", "goalGroup.force_deleted", "goalGroup.removed", "goalGroup.restored", "goalGroup.updated", "label.created", "label.force_deleted", "label.removed", "label.restored", "label.updated", "list.assignees.added", "list.assignees.removed", "list.created", "list.force_deleted", "list.goals.added", "list.goals.removed", "list.hiddenFor.added", "list.hiddenFor.removed", "list.removed", "list.restored", "list.updated", "member.created", "member.force_deleted", "member.removed", "member.restored", "member.updated", "message.created", "message.force_deleted", "message.removed", "message.restored", "message.updated", "portfolio.created", "portfolio.force_deleted", "portfolio.members.added", "portfolio.members.removed", "portfolio.removed", "portfolio.restored", "portfolio.updated", "presenceStatus.created", "presenceStatus.force_deleted", "presenceStatus.removed", "presenceStatus.restored", "presenceStatus.updated", "project.created", "project.force_deleted", "project.members.added", "project.members.removed", "project.removed", "project.restored", "project.transfer", "project.updated", "projectDashboard.created", "projectDashboard.force_deleted", "projectDashboard.removed", "projectDashboard.restored", "projectDashboard.updated", "projectFolder.created", "projectFolder.force_deleted", "projectFolder.removed", "projectFolder.restored", "projectFolder.updated", "recurringRule.created", "recurringRule.force_deleted", "recurringRule.removed", "recurringRule.restored", "recurringRule.updated", "reminder.created", "reminder.force_deleted", "reminder.removed", "reminder.restored", "reminder.updated", "reportChart.created", "reportChart.force_deleted", "reportChart.projects.added", "reportChart.projects.removed", "reportChart.removed", "reportChart.restored", "reportChart.updated", "role.created", "role.force_deleted", "role.removed", "role.restored", "role.updated", "status.assignees.added", "status.assignees.removed", "status.created", "status.force_deleted", "status.hiddenFor.added", "status.hiddenFor.removed", "status.removed", "status.restored", "status.updated", "task.assignees.added", "task.assignees.removed", "task.attachDocument", "task.connectedTasks.added", "task.connectedTasks.removed", "task.createTree", "task.created", "task.detachDocument", "task.force_deleted", "task.hiddenFor.added", "task.hiddenFor.removed", "task.labels.added", "task.labels.removed", "task.removed", "task.restored", "task.subscribers.added", "task.subscribers.removed", "task.updated", "taskHandoff.created", "taskHandoff.force_deleted", "taskHandoff.removed", "taskHandoff.restored", "taskHandoff.updated", "timeEntry.created", "timeEntry.force_deleted", "timeEntry.removed", "timeEntry.restored", "timeEntry.updated", "webhook.created", "webhook.force_deleted", "webhook.removed", "webhook.restored", "webhook.rotateSecret", "webhook.test", "webhook.updated" ] }, "minItems": 1, "maxItems": 100, "description": "Which events this webhook receives.\n\n**Grammar.** An entry is either an exact event name such as `task.created`, or a pattern. In a pattern each `*` stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so `task.*` matches `task.created` and `task.updated` but NOT the three-segment `task.assignees.added`; reach those with `task.*.*`, or by exact name. The bare `*` is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the [event catalog](https://developers.niftypm.com/docs/webhooks#event-catalog) is rejected at registration, so subscribe using the values listed below.\n\n**Lifecycle events.** Each resource below emits all five of `created`, `updated`, `removed`, `restored` and `force_deleted`, as `{resource}.{action}`:\n\n`annotation`, `chat`, `checkIn`, `checkInRequest`, `checklist`, `checklistItem`, `document`, `favorite`, `favoriteFolder`, `file`, `form`, `goal`, `goalGroup`, `label`, `list`, `member`, `message`, `portfolio`, `project`, `projectDashboard`, `projectFolder`, `recurringRule`, `reminder`, `reportChart`, `role`, `status`, `task`, `taskHandoff`, `presenceStatus`, `timeEntry`, `webhook`.\n\n**Membership events.** `{resource}.{relation}.added` and `{resource}.{relation}.removed` fire when a link is made or broken — one pair per relation listed here:\n\n- `checkIn` — `assignees`, `subscribers`\n- `checkInRequest` — `assignees`\n- `file` — `labels`, `subscribers`\n- `list` — `assignees`, `goals`, `hiddenFor`\n- `portfolio` — `members`\n- `reportChart` — `projects`\n- `status` — `assignees`, `hiddenFor`\n- `task` — `assignees`, `connectedTasks`, `hiddenFor`, `labels`, `subscribers`\n\n**Operation events.** Each named operation emits an event of the same name — the verb, not a past tense: `document.append`, `document.editText`, `file.createFromContent`, `file.createUploadUrl`, `file.uploadFromUrl`, `project.addMember`, `project.removeMember`, `project.transfer`, `task.attachDocument`, `task.createTree`, `task.detachDocument`, `webhook.rotateSecret`, `webhook.test`.", "example": [ "task.created", "task.updated", "project.*" ], "examples": [ [ "task.created", "task.updated", "project.*" ] ] }, "apiVersion": { "type": "string", "enum": [ "latest", "2026-03-20" ], "description": "Which payload format your endpoint receives, echoed back to you as the `X-Api-Version` request header. `latest` follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to `latest`.", "example": "latest", "examples": [ "latest" ] }, "active": { "type": "boolean", "description": "Whether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.", "example": true, "examples": [ true ] }, "expectedUpdatedAt": { "type": "string", "format": "date-time", "description": "Optional concurrency guard: the `updatedAt` you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh `updatedAt`.", "example": "2026-05-31T12:00:00.000Z", "examples": [ "2026-05-31T12:00:00.000Z" ] } }, "additionalProperties": false } }, "responses": { "Unauthorized": { "description": "Authentication required — missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Forbidden — the token lacks a scope required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The resource does not exist or is not accessible to this token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "The request failed validation — a malformed body, filter, sort field or page size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "Conflict": { "description": "Conflict with existing state — a duplicate name, a resource still in use, or an `expectedUpdatedAt` precondition that no longer holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded — retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "InternalError": { "description": "An unexpected error on our side (`code: internal_error`). The request was NOT retried for you and may or may not have been applied — send the same `Idempotency-Key` if you retry a write. Quote `requestId` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpstreamUnavailable": { "description": "The service is temporarily unavailable. Back off and retry. The body may not be the JSON error envelope.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, when present.", "schema": { "type": "integer", "example": 5 } } } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "example": 3000 } }, "RateLimitRemaining": { "description": "Requests still available in the current window. Two buckets apply to each request (per account and per IP); this reports whichever has less headroom.", "schema": { "type": "integer", "example": 2971 } }, "RateLimitReset": { "description": "Seconds until the current window resets and `X-RateLimit-Remaining` returns to `X-RateLimit-Limit`.", "schema": { "type": "integer", "example": 184 } } } }, "x-tagGroups": [ { "name": "Work", "tags": [ "task", "taskHandoff", "checklist", "checklistItem", "reminder", "recurringRule", "timeEntry" ] }, { "name": "Planning", "tags": [ "project", "projectFolder", "portfolio", "list", "status", "goal", "goalGroup", "form", "checkIn", "checkInRequest" ] }, { "name": "Content", "tags": [ "document", "file", "annotation", "message", "chat", "favorite", "favoriteFolder" ] }, { "name": "People & access", "tags": [ "member", "role", "actor", "presenceStatus" ] }, { "name": "Automation & integrations", "tags": [ "webhook" ] }, { "name": "Reporting", "tags": [ "reportChart", "projectDashboard", "projectActivity", "customField", "label" ] } ] }