> ## Documentation Index > Fetch the complete documentation index at: https://docs.testdino.com/llms.txt > Use this file to discover all available pages before exploring further. # Create session > Create an exploratory testing session. Requires a writer-role PAT. ## OpenAPI ````yaml api-reference/openapi.yml POST /{projectId}/sessions openapi: 3.0.3 info: title: TestDino Public API version: 1.0.0 description: > Public API for TestDino: read access to test analytics, manual tests, and project data, plus manual-testing write endpoints. **Read (GET) endpoints** cover analytics, runs, cases, and project data. **Write endpoints (POST/PATCH)** create and update manual-testing entities: suites, cases, releases, sessions, and manual runs (including per-case verdicts). Query parameters are **endpoint-specific**; see each operation for supported filters, enums, and defaults. Writes require a PAT whose owner holds a writer role (owner/admin/member) on the project's organization; a viewer-role token gets `403`. ## Authentication All endpoints require a Bearer token in the `Authorization` header: ``` Authorization: Bearer td_pat_ ``` Use a user PAT (`td_pat_` prefix) scoped to the organization/project. ## Rate Limiting - **Reads (per-token):** 100 requests/minute - **Writes (per-token):** 60 requests/minute - **Manual run creation (per-token):** 10 requests/minute - **Per-IP (pre-auth):** 200 requests/minute - **PDF generation:** 1 request/minute per token Standard headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` ## Response Format **Success:** ```json { "success": true, "data": { ... }, "pagination": { ... } } ``` **Error:** ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message" } } ``` ## Time windows and date filters There is **no global date-filter convention**. Each endpoint documents its own parameters: | Endpoint family | Parameter | Allowed values | |-----------------|-----------|------------------| | Test runs list | `start_date`, `end_date` | RFC3339 timestamps (both required together) | | Explorer, specs, analytics | `days` | Integer snapped to **7, 30, or 90** (see each endpoint) | | Test runs list | — | No preset `period` / `dateRange` params | | Dashboard, filters | — | **No query params** (fixed downstream snapshot) | ## Served by This contract is served by the **MCP service** (the gateway), which authenticates the `td_pat_` user PAT and fans out to data-handler / tcm / user-service / billing. It is **read-only** — webhook subscription management (the previous public API's only write surface) is owned by the **integration service** and is not part of this contract. ## Implementation status All 17 routes are mounted (auth + rate-limit). Most call their real downstream today; a few still have lean shapes or pending owners (notably `usage` → billing). Live vs pending detail: `docs/DOWNSTREAM_WORK.md`. contact: name: TestDino Support url: https://docs.testdino.com servers: - url: https://api.testdino.com/api/v1/public description: Production security: - BearerAuth: [] tags: - name: Token Info description: Token introspection and project metadata - name: Test Runs description: List, inspect, and drill into test runs - name: Test Cases description: Automated test case details and history - name: Specs description: Project-level spec file health - name: Manual Tests description: Manual test suites and cases (read-only) - name: Test Case Explorer description: Aggregated test case metrics explorer - name: Context description: >- Debugging payload at three levels (run / suite / test) — error, steps, failure window, attempts, attachments, trace, deep links, and a copy-paste retry command. Designed for AI agents and CI scripts. - name: Dashboard description: Project health overview - name: Filters description: Available filter values (environments, branches, developers, tags) - name: Reports description: PDF report generation and download - name: Analytics description: Consolidated analytics summary and test case execution performance - name: Usage description: Subscription usage and limits paths: /{projectId}/sessions: post: tags: - Sessions summary: Create an exploratory session description: >- Creates a session. Requires a writer-role PAT (viewer → `403`). Attachments not supported in v1. parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/idempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' responses: '201': description: Session created content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: parameters: projectId: name: projectId in: path required: true schema: type: string description: >- The project identifier (e.g. `project_abc123`). Must match the project associated with your PAT. idempotencyKey: name: Idempotency-Key in: header required: false schema: type: string description: > Optional but recommended on create (`POST`) requests. Send a unique value (e.g. a UUID) per logical create. A retry with the same key within 24h replays the original response instead of creating a duplicate. Same key with a different body returns `422 IDEMPOTENCY_KEY_REUSE`; a key for a request still in flight returns `409`. Omitting the header is allowed (no deduplication). schemas: CreateSessionRequest: type: object required: - name additionalProperties: false properties: name: type: string maxLength: 255 mission: type: string description: Rich HTML charter. sessionType: type: string config: type: string environment: type: string releaseId: type: string assigneeUserId: type: string description: User _id or email. state: type: string description: Project-configured workflow state. estimate: type: integer minimum: 0 description: Estimate in minutes. tags: type: array items: type: string description: JSON array of strings. linkedIssues: type: array items: type: object SuccessEnvelope: type: object properties: success: type: boolean enum: - true data: type: object pagination: $ref: '#/components/schemas/Pagination' Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer hasNext: type: boolean hasPrev: type: boolean ErrorEnvelope: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string message: type: string responses: ValidationError: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Unauthorized: description: Missing, invalid, expired, or revoked token content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: UNAUTHORIZED message: Invalid or unknown user PAT Forbidden: description: Token not authorized for this project content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: RATE_LIMIT_EXCEEDED message: Too many requests securitySchemes: BearerAuth: type: http scheme: bearer description: User PAT (td_pat_) scoped to the target project ````