> ## Documentation Index > Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Record Playtime Session > Records a single playtime session. **Auto attribution:** - If `campaignId` is not specified, automatically attributed to the project's active campaign sponsor **Idempotency:** - The unique key is `projectId` + `sessionId` - A duplicate `sessionId` is NOT an error: the existing row is kept and the response returns `recorded: false` ## OpenAPI ````yaml /api_docs/openapi.yaml post /v1/server/playtime/sessions openapi: 3.0.3 info: title: PlayCamp SDK API description: > PlayCamp SDK API - Game analytics and creator campaign integration API ## Required Integration APIs (Server API) 3 APIs that must be integrated for campaign operation: - `POST /v1/server/sponsors` - User boosts a creator - `POST /v1/server/coupons/validate` - Validate coupon code - `POST /v1/server/payments` - Register in-game payment ## Authentication - **Client API**: `Authorization: Bearer {CLIENT_KEY_ID}:{CLIENT_SECRET}` - **Server API**: `Authorization: Bearer {SERVER_KEY_ID}:{SERVER_SECRET}` ## Servers - **Live**: https://sdk-api.playcamp.io (Production data) - **Sandbox**: https://sandbox-sdk-api.playcamp.io (Test data) ## Key Types - **Client Key**: For game client (read-only - campaign, creator queries) - **Server Key**: For game server (read/write - coupon redemption, payment registration, etc.) ## Test Mode (isTest) Before campaign launch, use `isTest: true` parameter to test API integration. - Request parameter validation is performed identically to production - Returns mock data without recording to actual DB - Verify integration in Sandbox environment before campaign launch, then remove `isTest` parameter for actual campaign version: 1.1.0 contact: name: PlayCamp Support servers: - url: https://sdk-api.playcamp.io description: Live Server - url: https://sandbox-sdk-api.playcamp.io description: Sandbox Server - url: http://localhost:3001 description: Local Live Server - url: http://localhost:3003 description: Local Sandbox Server security: [] tags: - name: Health description: Server health check - name: Client Campaign description: Campaign queries (Client API) - name: Client Creator description: Creator queries (Client API) - name: Client Coupon description: Coupon validation (Client API) - name: Client Sponsor description: Boost status queries — Sponsor API (Client API) - name: Server Campaign description: Campaign queries (Server API) - name: Server Creator description: Creator queries (Server API) - name: Server Coupon description: Coupon management (Server API) - name: Server Sponsor description: Boost management — Sponsor API (Server API) - name: Server Payment description: Payment management (Server API) - name: Server Playtime description: Playtime session management (Server API) - name: Server Webhook description: Webhook management (Server API) - name: Server Webview description: WebView management (Server API) paths: /v1/server/playtime/sessions: post: tags: - Server Playtime summary: Record Playtime Session description: > Records a single playtime session. **Auto attribution:** - If `campaignId` is not specified, automatically attributed to the project's active campaign sponsor **Idempotency:** - The unique key is `projectId` + `sessionId` - A duplicate `sessionId` is NOT an error: the existing row is kept and the response returns `recorded: false` operationId: serverCreatePlaytimeSession requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/CreatePlaytimeSessionRequest' - type: object properties: callbackId: type: string description: >- Webhook tracking ID (included in webhook events triggered by this request) isTest: type: boolean default: false description: Test mode (does not create actual data) responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PlaytimeSession' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' security: - ServerAuth: [] components: schemas: CreatePlaytimeSessionRequest: type: object required: - sessionId - userId - durationSeconds - startedAt - endedAt properties: sessionId: type: string description: Client-generated unique session ID userId: type: string description: User ID durationSeconds: type: integer minimum: 1 description: Session duration in seconds startedAt: type: string format: date-time description: | Session start time (ISO 8601 UTC format) - Format: `YYYY-MM-DDTHH:mm:ss.sssZ` - Example: `2024-01-15T10:30:00.000Z` endedAt: type: string format: date-time description: > Session end time (ISO 8601 UTC format, must be greater than or equal to `startedAt`) - Format: `YYYY-MM-DDTHH:mm:ss.sssZ` - Example: `2024-01-15T11:00:00.000Z` campaignId: type: string description: >- Campaign ID (optional). If omitted, automatically attributed to the project's active campaign sponsor creatorKey: type: string pattern: ^[A-Z0-9]{5}$ description: Creator key (optional, exactly 5 uppercase alphanumeric characters) platform: type: string enum: - iOS - Android - Web - Roblox - Other description: Playtime platform (optional, server defaults to `Other`) metadata: type: object description: Arbitrary key/value metadata additionalProperties: true PlaytimeSession: type: object description: Recorded playtime session properties: sessionId: type: string userId: type: string durationSeconds: type: integer recorded: type: boolean description: > Whether the session was newly recorded. - `true`: A new session row was created - `false`: A duplicate `sessionId` was ignored and the existing row was kept (not an error) createdAt: type: string format: date-time ValidationError: type: object required: - status - error - message - code - details properties: status: type: integer example: 400 error: type: string example: Bad Request message: type: string example: Validation failed code: type: string example: VALIDATION_ERROR details: type: array items: type: object properties: path: type: string description: Field path where error occurred message: type: string description: Error message example: - path: userId message: Required - path: amount message: Expected number, received string Error: type: object required: - status - error - message - code properties: status: type: integer description: HTTP status code error: type: string description: HTTP status name message: type: string description: Detailed error message code: type: string description: | Error codes: - `VALIDATION_ERROR`: Request parameter validation failed - `BAD_REQUEST`: Invalid request - `UNAUTHORIZED`: Authentication failed (API key error) - `FORBIDDEN`: Access denied - `NOT_FOUND`: Resource not found - `CONFLICT`: Duplicate resource (already exists) - `INTERNAL_ERROR`: Internal server error details: type: array description: Validation error details (for VALIDATION_ERROR) items: type: object properties: path: type: string message: type: string example: status: 404 error: Not Found message: 'Payment not found: txn-12345' code: NOT_FOUND responses: ValidationError: description: Request parameter validation failed content: application/json: schema: $ref: '#/components/schemas/ValidationError' Unauthorized: description: Authentication failed (API key error) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 401 error: Unauthorized message: Invalid API key code: UNAUTHORIZED Forbidden: description: Access denied (e.g., accessing Server API with Client key) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 403 error: Forbidden message: Access denied code: FORBIDDEN RateLimited: description: Too many requests (rate limit exceeded) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 429 error: Too Many Requests message: Rate limit exceeded code: RATE_LIMITED securitySchemes: ServerAuth: type: http scheme: bearer description: 'Server API Key (format: {keyId}:{secret})' ````