> ## Documentation Index > Fetch the complete documentation index at: https://docs.davinci-app.com/llms.txt > Use this file to discover all available pages before exploring further. # Search project cards > Returns a bounded flat card page plus tag, assignee, linked-team, workflow-status, and accessible active/planned sprint filter options. Cards default to open only. Values within one repeated/comma-separated filter are ORed; distinct filter dimensions are ANDed. `includeNoTeam` extends the team facet with cards having no placement, and `includeUnassigned` extends the assignee facet with cards having no user links. Deadline and effort bounds are inclusive. Within either range dimension, its include-no-value flag ORs null-valued cards with bounded non-null matches; using only the flag matches only null-valued cards. Range dimensions AND with every other facet. Invalid instants, negative/non-integer effort values, reversed ranges, and cursors issued for different ranges return canonical 400 errors: `INVALID_CARD_DEADLINE_FILTER`, `INVALID_CARD_DEADLINE_RANGE`, `INVALID_CARD_EFFORT_FILTER`, `INVALID_CARD_EFFORT_RANGE`, or `INVALID_CARD_CURSOR`. Results use an explicit stable sort and opaque cursor. ## OpenAPI ````yaml /openapi/davinci-public.v2.yaml get /api/v2/projects/{projectId}/cards openapi: 3.1.0 info: title: Davinci Public API version: 2.0.0 description: > Public Routing Server API contract for Davinci integrations and official SDKs. Most operations live on the canonical `/api/v2/projects` mount and accept a personal access token (`dav_ak_live_…` / `dav_ak_test_…`) or browser access token. Evaluation-run creation is the deliberate exception: it accepts only a `purpose=automation` grant issued to a running Code execution. Project membership and role are checked on every user call, and an API key is additionally bounded by the permission ceiling derived from its scopes — a key can never exceed what its owner can do, and usually does less. Collaboration operations (invitations, membership changes, ownership transfer) are deliberately absent: they require a browser session and are not part of the programmatic surface. ## Two planes Most operations are **control plane**: they run on the Routing Server, take small requests, and answer quickly. A few are **data plane**, marked `x-plane: data`, and go straight to the machine holding your project — the only practical way to move multi-gigabyte files or hold a connection open for half an hour. Data-plane operations use a different host and a different credential. Create a session on a project and it returns both: a `dataPlane.url` to send to and a short-lived `dataPlane.token` (`dav_gr_…`, a *grant*) to send with. A grant reaches exactly one project, carries no more permission than the key that minted it, expires in minutes, and dies when its session closes. It is not interchangeable with an API key in either direction. The data-plane host never names a specific machine, so a project that moves between machines mid-session stays reachable at the same URL. servers: - url: https://davinci-app.com description: Production (control plane) - url: https://davinci-app.com/data description: >- Production (data plane). Serves the operations marked `x-plane: data`, using a session's grant rather than an API key. security: - ApiKeyBearer: [] tags: - name: Projects description: >- Create, inspect, open, close, and delete projects, and manage their attached files. - name: Content description: > Read and write the objects a project is made of. These reach the running project rather than storage, so they see uncommitted work — and so they open the project if it is not already open. - name: Branches description: > Branches, commits, and the history of a single object. A commit captures the running project's state, so these operations need the branch loaded, which they arrange for the caller. - name: Sessions description: > A session opens a project, holds it open, and issues the grant that reaches the data plane. It is the programmatic equivalent of having a project open in a browser tab: while it lives, the project stays loaded. It is also where the agent lives. Send it a prompt, read its status from the session, read the transcript back, and stop a run that is going the wrong way. - name: AgentModels description: > Chat models available to your account. The returned keys are the values accepted by the session message API; availability follows your subscription, tenant, and any profile assigned to your account. - name: Tools description: > Invoke one of the agent's tools yourself, without the agent. Useful when you already know the operation you want and do not need a model to choose it — and when you want a deterministic result rather than an interpreted one. A tool is still held to the permissions of the credential invoking it, so a key cannot reach through a tool to something its scopes exclude. - name: Files description: > Data-plane file transfer. These reach your project's machine directly using a session's grant, which is what allows request bodies far larger than the control plane accepts. - name: Usage description: > What your models cost, broken down by model, project, session, or day. These read the usage ledger, which records one event per completed provider call — not your credit balance, which is `/api/v2/billing`. Usage is reported on an interval rather than per call, so a run that is still going may not be fully counted yet. Every response carries `asOf`, the moment the newest counted event was recorded, so you can see how current a total is instead of guessing. This is separate from `projects:read` on purpose: a key that reads your project data is not thereby allowed to see what you spend. - name: Evaluations description: | Lifecycle for the ephemeral target sandbox an evaluation runs against. Creation is available only to a `purpose=automation` grant issued to a running Code execution, so a sandbox always belongs to code rather than to a person's key. It returns a second, `purpose=evaluation` grant bound to the new sandbox; it never upgrades or replaces the source credential. - name: Tests description: > Asynchronously run an authored Test. The Test executes its linked Code object and applies its native evaluation criteria to derive the verdict. This is one way to start Code, not a prerequisite for anything the Code can do: the same function called directly holds the same authority. - name: Organizations description: Discover organizations available as containers for team planning. - name: Cards description: > Project-scoped agile cards, their index hierarchy, comments, tags, assignees, card dependencies, and design-object references. Project access is checked on every call; an inaccessible project is reported as not found. - name: Teams description: > Organization-scoped team boards, linked projects, workflow columns, sprints, analytics, and card placements. Team visibility is privacy preserving: inaccessible organizations, private teams, and cross-organization ids are reported as not found rather than revealing that they exist. paths: /api/v2/projects/{projectId}/cards: parameters: - $ref: '#/components/parameters/ProjectId' get: tags: - Cards summary: Search project cards description: > Returns a bounded flat card page plus tag, assignee, linked-team, workflow-status, and accessible active/planned sprint filter options. Cards default to open only. Values within one repeated/comma-separated filter are ORed; distinct filter dimensions are ANDed. `includeNoTeam` extends the team facet with cards having no placement, and `includeUnassigned` extends the assignee facet with cards having no user links. Deadline and effort bounds are inclusive. Within either range dimension, its include-no-value flag ORs null-valued cards with bounded non-null matches; using only the flag matches only null-valued cards. Range dimensions AND with every other facet. Invalid instants, negative/non-integer effort values, reversed ranges, and cursors issued for different ranges return canonical 400 errors: `INVALID_CARD_DEADLINE_FILTER`, `INVALID_CARD_DEADLINE_RANGE`, `INVALID_CARD_EFFORT_FILTER`, `INVALID_CARD_EFFORT_RANGE`, or `INVALID_CARD_CURSOR`. Results use an explicit stable sort and opaque cursor. operationId: searchCards parameters: - $ref: '#/components/parameters/CardQuery' - $ref: '#/components/parameters/CardState' - $ref: '#/components/parameters/CardTagIds' - $ref: '#/components/parameters/CardAssigneeIds' - $ref: '#/components/parameters/CardIncludeUnassigned' - $ref: '#/components/parameters/CardTeamIds' - $ref: '#/components/parameters/CardIncludeNoTeam' - $ref: '#/components/parameters/CardStatusIds' - $ref: '#/components/parameters/CardSprintIds' - $ref: '#/components/parameters/CardDeadlineFrom' - $ref: '#/components/parameters/CardDeadlineTo' - $ref: '#/components/parameters/CardIncludeNoDeadline' - $ref: '#/components/parameters/CardEffortMin' - $ref: '#/components/parameters/CardEffortMax' - $ref: '#/components/parameters/CardIncludeNoEffort' - $ref: '#/components/parameters/CardSort' - $ref: '#/components/parameters/CardPageLimit' - $ref: '#/components/parameters/CardCursor' responses: '200': description: Flat project-card search page. content: application/json: schema: $ref: '#/components/schemas/CardSearchResponse' '400': $ref: '#/components/responses/BadRequest' '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' security: - ApiKeyBearer: [] components: parameters: ProjectId: name: projectId in: path required: true schema: type: string minLength: 1 description: Project id. May be compound in the form `{projectId}--{branchName}`. CardQuery: name: q in: query required: false schema: type: string maxLength: 200 description: >- Case-insensitive substring search across card name, description, and resolution. CardState: name: state in: query required: false schema: type: string enum: - open - closed - all default: open description: Project-global card lifecycle state. CardTagIds: name: tagIds in: query required: false schema: type: array maxItems: 50 items: type: string format: uuid style: form explode: true description: Match cards carrying any selected project tag. CardAssigneeIds: name: assigneeIds in: query required: false schema: type: array maxItems: 50 items: type: string format: uuid style: form explode: true description: Match cards assigned to any selected project member. CardIncludeUnassigned: name: includeUnassigned in: query required: false schema: type: boolean default: false description: >- OR cards with no user links into the assignee facet. This is not a sentinel assignee ID. CardTeamIds: name: teamIds in: query required: false schema: type: array maxItems: 50 items: type: string format: uuid style: form explode: true description: Match cards placed on any selected linked team. CardIncludeNoTeam: name: includeNoTeam in: query required: false schema: type: boolean default: false description: >- OR cards with no team placement into the team facet. This is not a sentinel team ID. CardStatusIds: name: statusIds in: query required: false schema: type: array maxItems: 50 items: type: string format: uuid style: form explode: true description: Match cards whose selected-team placement uses any selected status. CardSprintIds: name: sprintIds in: query required: false schema: type: array maxItems: 50 items: type: string format: uuid style: form explode: true description: Match cards whose team placement uses any selected sprint. CardDeadlineFrom: name: deadlineFrom in: query required: false schema: type: string format: date-time description: Inclusive ISO 8601 instant lower bound for non-null card deadlines. CardDeadlineTo: name: deadlineTo in: query required: false schema: type: string format: date-time description: Inclusive ISO 8601 instant upper bound for non-null card deadlines. CardIncludeNoDeadline: name: includeNoDeadline in: query required: false schema: type: boolean default: false description: >- OR cards with a null deadline into bounded deadline matches. With no deadline bounds, match only cards with no deadline. CardEffortMin: name: effortMin in: query required: false schema: type: integer minimum: 0 description: Inclusive lower bound for non-null card effort. CardEffortMax: name: effortMax in: query required: false schema: type: integer minimum: 0 description: Inclusive upper bound for non-null card effort. CardIncludeNoEffort: name: includeNoEffort in: query required: false schema: type: boolean default: false description: >- OR cards with null effort into bounded effort matches. With no effort bounds, match only cards with no effort. CardSort: name: sort in: query required: false schema: type: string enum: - created_asc - created_desc - updated_asc - updated_desc - deadline_asc - deadline_desc - effort_asc - effort_desc - name_asc - name_desc default: created_desc description: Stable card sort; card ID is the deterministic tie-breaker. CardPageLimit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 100 description: Maximum cards returned. CardCursor: name: cursor in: query required: false schema: type: string maxLength: 2048 description: Opaque cursor returned as `meta.nextCursor` or `meta.previousCursor`. schemas: CardSearchResponse: type: object required: - cards - meta properties: cards: type: array items: $ref: '#/components/schemas/CardSearchCard' filterOptions: $ref: '#/components/schemas/CardFilterOptions' meta: $ref: '#/components/schemas/CardSearchPageMeta' additionalProperties: false CardSearchCard: type: object required: - id - name - description - resolution - created_by_user - created_at - updated_at - deadline - is_open - project_id - effort - tag_ids - user_ids - team_ids - team_status_ids - sprint_ids - team_statuses - team_placements - history_head_id - history_head_sequence properties: id: type: string format: uuid name: type: string description: type: - string - 'null' resolution: type: - string - 'null' maxLength: 10000 description: >- Optional Markdown resolution; closing or reopening the card does not clear it. created_by_user: type: - string - 'null' format: uuid author_display_name: type: - string - 'null' description: Display name of the user who created the card, when available. created_at: type: - string - 'null' format: date-time closed_at: type: - string - 'null' format: date-time readOnly: true description: >- Timestamp of the latest transition to the closed state; null while open. updated_at: type: - string - 'null' format: date-time deadline: type: - string - 'null' format: date-time is_open: type: boolean project_id: type: string format: uuid effort: type: - integer - 'null' minimum: 0 description: >- Unit-agnostic estimate, commonly interpreted as story points or hours. tag_ids: type: array items: type: string format: uuid user_ids: type: array items: type: string format: uuid team_ids: type: array items: type: string format: uuid team_status_ids: type: array items: type: string format: uuid sprint_ids: type: array items: type: string format: uuid team_statuses: type: array description: Deterministically ordered placed-team status metadata. items: $ref: '#/components/schemas/CardPlacementStatus' team_placements: type: array description: Deterministically ordered team placement filter metadata. items: $ref: '#/components/schemas/CardPlacement' history_head_id: $ref: '#/components/schemas/NullableHistoryHeadId' history_head_sequence: $ref: '#/components/schemas/NullableHistoryHeadSequence' additionalProperties: true CardFilterOptions: type: object required: - tags - teams - assignees - statuses - sprints properties: tags: type: array items: $ref: '#/components/schemas/CardTagFilterOption' teams: type: array items: $ref: '#/components/schemas/CardTeamFilterOption' assignees: type: array items: $ref: '#/components/schemas/CardAssignee' statuses: type: array items: $ref: '#/components/schemas/CardStatusFilterOption' sprints: type: array items: $ref: '#/components/schemas/CardSprintFilterOption' additionalProperties: false CardSearchPageMeta: type: object required: - limit - hasMore - state - sort - previousCursor - nextCursor properties: limit: type: integer minimum: 1 hasMore: type: boolean total: type: integer minimum: 0 state: type: string enum: - open - closed - all sort: type: string projection: type: string enum: - full - index - mention hydrateOpen: type: boolean pageStart: type: integer minimum: 0 pageEnd: type: integer minimum: 0 previousCursor: type: - string - 'null' nextCursor: type: - string - 'null' additionalProperties: false ErrorEnvelope: description: > The error shape for every failure on this API, whether it was refused by the credential layer before reaching a domain or by the domain itself. Branch on `code`, which is stable. `message` is for a person reading a log or a dialog and may be reworded. `details` carries fields specific to one failure — a project-limit refusal reports its numbers there — and is absent when there are none. type: object required: - success - error properties: success: type: boolean const: false error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true additionalProperties: true additionalProperties: true CardPlacementStatus: type: object required: - team_id - status_id - status_name - status_color - sprint_id properties: team_id: type: string format: uuid status_id: type: string format: uuid status_name: type: - string - 'null' status_color: type: - string - 'null' sprint_id: type: - string - 'null' format: uuid additionalProperties: false CardPlacement: type: object required: - team_id - status_id - sprint_id properties: team_id: type: string format: uuid status_id: type: - string - 'null' format: uuid sprint_id: type: - string - 'null' format: uuid additionalProperties: false NullableHistoryHeadId: type: - string - 'null' format: uuid description: >- Latest committed card-history row ID; null only before a card has history. NullableHistoryHeadSequence: type: - string - 'null' pattern: ^\d+$ description: Globally monotonic card-history sequence. CardTagFilterOption: type: object required: - id - name - color properties: id: type: string format: uuid name: type: string color: type: string additionalProperties: false CardTeamFilterOption: type: object required: - id - name properties: id: type: string format: uuid name: type: string additionalProperties: false CardAssignee: type: object required: - id - display_name properties: id: type: string format: uuid display_name: type: - string - 'null' additionalProperties: false CardStatusFilterOption: type: object required: - id - name - color - teamId - teamName properties: id: type: string format: uuid name: type: string color: type: string teamId: type: string format: uuid teamName: type: string additionalProperties: false CardSprintFilterOption: type: object required: - id - name - status - teamId - teamName properties: id: type: string format: uuid name: type: string status: type: string enum: - active - planned teamId: type: string format: uuid teamName: type: string additionalProperties: false responses: BadRequest: description: | Malformed request parameters or body. Agile requests may return `INVALID_PAGINATION` or `INVALID_IDEMPOTENCY_KEY`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Unauthorized: description: > No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: > Authenticated but not authorized. Either the acting user lacks the required resource permission, the key's scope ceiling excludes it, or the endpoint rejects this credential type (`CREDENTIAL_NOT_PERMITTED`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' NotFound: description: > The resource does not exist in the parent named by the path, or is hidden from the caller. Absence and privacy denial are deliberately indistinguishable so project, organization, and private-team existence cannot be probed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: Request rate exceeded, either globally or for this key. headers: Retry-After: schema: type: integer minimum: 1 description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyBearer: type: http scheme: bearer bearerFormat: dav_ak_live_... or dav_ak_test_... x-default: dav_ak_live_your_token description: > Personal access token. The scopes granted at issuance determine both which operations the key may call and the ceiling on the resource permissions it can exercise. Each scope family is a ladder: `projects:manage` implies `projects:write` and `projects:read`; `cards:manage` implies `cards:write` and `cards:read`; and `teams:manage` implies `teams:write` and `teams:read`. These are named API capability bundles, not blanket domain roles: `manage` exposes only the permissions enumerated for that scope and never bypasses the acting user's current role-based access. ````