{"openapi":"3.1.0","info":{"title":"Talqen Platform API","version":"1.0.0","description":"Talqen public API gateway. Business endpoints are served under /v1. Human-readable documentation lives at /docs on the API hostname. Developer credentials are managed at developer.talqen.net."},"servers":[{"url":"https://api.talqen.net/v1","description":"Production"},{"url":"https://api-staging.talqen.net/v1","description":"Staging"}],"tags":[{"name":"Metadata","description":"Unversioned gateway metadata routes served from the API hostname root."},{"name":"Applications","description":"Application review and decision endpoints."},{"name":"Integration","description":"Developer application integration metadata for Talqen Connect."},{"name":"Staff","description":"Workspace staff self-service endpoints for trusted integrations."},{"name":"Activity","description":"Workspace activity tracking and leaderboard endpoints."}],"paths":{"/health":{"servers":[{"url":"https://api.talqen.net","description":"Production gateway"},{"url":"https://api-staging.talqen.net","description":"Staging gateway"}],"get":{"tags":["Metadata"],"operationId":"getHealth","summary":"Health check","description":"Infrastructure health check. No authentication required.","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/version":{"servers":[{"url":"https://api.talqen.net","description":"Production gateway"},{"url":"https://api-staging.talqen.net","description":"Staging gateway"}],"get":{"tags":["Metadata"],"operationId":"getVersion","summary":"Version metadata","description":"Returns safe deployment metadata. No authentication required.","responses":{"200":{"description":"Version metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}}}},"/openapi.json":{"servers":[{"url":"https://api.talqen.net","description":"Production gateway"},{"url":"https://api-staging.talqen.net","description":"Staging gateway"}],"get":{"tags":["Metadata"],"operationId":"getOpenApiDocument","summary":"OpenAPI document","description":"Returns this OpenAPI 3.1 specification.","responses":{"200":{"description":"OpenAPI document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/applications/submissions/{submissionId}/accept":{"post":{"tags":["Applications"],"operationId":"acceptApplicationSubmission","summary":"Accept an application submission","description":"Records an acceptance decision for a submission. Requires a dashboard user bearer token and an Idempotency-Key header.","security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/WorkspaceSelectorHeader"},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationAcceptRequest"}}}},"responses":{"200":{"description":"Submission accepted.","headers":{"X-Request-Id":{"$ref":"#/components/parameters/RequestIdResponseHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationAcceptResponse"}}}},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"},"404":{"$ref":"#/components/responses/ApiErrorResponse"},"409":{"$ref":"#/components/responses/ApiErrorResponse"},"422":{"$ref":"#/components/responses/ApiErrorResponse"}}}},"/applications/submissions/{submissionId}/mark-under-review":{"post":{"tags":["Applications"],"operationId":"markApplicationSubmissionUnderReview","summary":"Mark an application submission under review","description":"Transitions a submission from submitted to under_review. Requires applications.review permission, a dashboard user bearer token, and an Idempotency-Key header.","security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/WorkspaceSelectorHeader"},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationReviewNoteRequest"}}}},"responses":{"200":{"description":"Submission marked under review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationMarkUnderReviewResponse"}}}},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"},"404":{"$ref":"#/components/responses/ApiErrorResponse"},"409":{"$ref":"#/components/responses/ApiErrorResponse"},"422":{"$ref":"#/components/responses/ApiErrorResponse"}}}},"/applications/submissions/{submissionId}/reject":{"post":{"tags":["Applications"],"operationId":"rejectApplicationSubmission","summary":"Reject an application submission","description":"Records a rejection decision. Requires applications.decide permission, a dashboard user bearer token, and an Idempotency-Key header.","security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/WorkspaceSelectorHeader"},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationReviewNoteRequest"}}}},"responses":{"200":{"description":"Submission rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationRejectResponse"}}}},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"},"404":{"$ref":"#/components/responses/ApiErrorResponse"},"409":{"$ref":"#/components/responses/ApiErrorResponse"},"422":{"$ref":"#/components/responses/ApiErrorResponse"}}}},"/applications/submissions/{submissionId}/review":{"patch":{"tags":["Applications"],"operationId":"updateApplicationSubmissionReview","summary":"Update reviewer score and notes","description":"Partially updates reviewer score and/or notes without changing submission status. Requires applications.review permission, a dashboard user bearer token, and an Idempotency-Key header. Omitted fields are left unchanged; explicit null clears a field. Request validation errors return 400; attempts to update accepted or rejected submissions return 422.","security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/WorkspaceSelectorHeader"},{"$ref":"#/components/parameters/IdempotencyKeyHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationReviewUpdateRequest"}}}},"responses":{"200":{"description":"Review data updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationReviewUpdateResponse"}}}},"400":{"description":"Malformed JSON, empty patch body, invalid score type or range, reviewer notes too long, or invalid request shape.","$ref":"#/components/responses/ApiErrorResponse"},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"},"404":{"$ref":"#/components/responses/ApiErrorResponse"},"409":{"$ref":"#/components/responses/ApiErrorResponse"},"422":{"description":"Submission status forbids review updates (accepted or rejected).","$ref":"#/components/responses/ApiErrorResponse"}}}},"/integration":{"get":{"tags":["Integration"],"operationId":"getIntegration","summary":"Integration context","description":"Returns workspace, application, scopes, features, and Discord binding metadata for the authenticated developer API credential. Talqen Connect is a trusted workspace-scoped integration actor; optional X-Discord-Guild-Id is a binding consistency check only.","security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/DiscordGuildIdHeader"}],"responses":{"200":{"description":"Integration context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationResponse"}}}},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"}}}},"/staff/me":{"get":{"tags":["Staff"],"operationId":"getStaffMe","summary":"Self staff profile","description":"Resolves the invoking Discord user to a workspace staff profile using the authenticated credential, guild binding, and X-Acting-Discord-User-Id. Self-service only.","security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/DiscordGuildIdHeader"},{"$ref":"#/components/parameters/ActingDiscordUserIdHeader"}],"responses":{"200":{"description":"Self staff profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffMeResponse"}}}},"400":{"$ref":"#/components/responses/ApiErrorResponse"},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"},"404":{"$ref":"#/components/responses/ApiErrorResponse"}}}},"/activity/me/summary":{"get":{"tags":["Activity"],"operationId":"getActivityMeSummary","summary":"Self activity summary","description":"Returns today, week, previous week, and month activity totals for the invoking Discord-linked staff member. Active shift elapsed seconds are reported separately and are not added to completed-minute totals.","security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CorrelationIdHeader"},{"$ref":"#/components/parameters/DiscordGuildIdHeader"},{"$ref":"#/components/parameters/ActingDiscordUserIdHeader"}],"responses":{"200":{"description":"Self activity summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityMeSummaryResponse"}}}},"400":{"$ref":"#/components/responses/ApiErrorResponse"},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"},"404":{"$ref":"#/components/responses/ApiErrorResponse"}}}},"/activity/leaderboard":{"get":{"tags":["Activity"],"operationId":"getActivityLeaderboard","summary":"Activity leaderboard","description":"Cursor-paginated workspace activity leaderboard for week or month periods.","security":[{"apiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/CorrelationIdHeader"},{"name":"period","in":"query","schema":{"type":"string","enum":["week","month"]}},{"name":"start","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"end","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursorTotalSeconds","in":"query","schema":{"type":"integer"}},{"name":"cursorStaffId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"departmentId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"includeInactive","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Leaderboard page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityLeaderboardResponse"}}}},"400":{"$ref":"#/components/responses/ApiErrorResponse"},"401":{"$ref":"#/components/responses/ApiErrorResponse"},"403":{"$ref":"#/components/responses/ApiErrorResponse"}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","required":["status","service","timestamp"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string","example":"talqen-api"},"timestamp":{"type":"string","format":"date-time"}}},"VersionResponse":{"type":"object","required":["service","apiVersion","build","environment"],"properties":{"service":{"type":"string","example":"talqen-api"},"apiVersion":{"type":"string","example":"v1"},"build":{"type":"string","example":"local"},"environment":{"type":"string","example":"staging"}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string","example":"The requested resource was not found."},"requestId":{"type":"string","example":"req_..."},"details":{"type":"object","additionalProperties":true}}}}},"ApplicationAcceptRequest":{"type":"object","properties":{"reviewNote":{"type":"string","maxLength":5000},"createStaffProfile":{"type":"boolean","description":"Optional override of the workspace default (settings.createStaffProfileOnAccept). Requires staff.create permission; ignored otherwise."}}},"ApplicationReviewNoteRequest":{"type":"object","properties":{"reviewNote":{"type":"string","maxLength":5000}}},"ApplicationAcceptResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["submissionId","status","acceptedAt","staffProfileCreated"],"properties":{"submissionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["accepted"]},"acceptedAt":{"type":"string","format":"date-time"},"staffProfileCreated":{"type":"boolean"},"staffProfileId":{"type":"string","format":"uuid","nullable":true},"commandId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}}},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"ApplicationMarkUnderReviewResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["submissionId","status","reviewedAt","commandId","eventId"],"properties":{"submissionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["under_review"]},"reviewedAt":{"type":"string","format":"date-time"},"commandId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}}},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"ApplicationRejectResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["submissionId","status","rejectedAt","commandId","eventId"],"properties":{"submissionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["rejected"]},"rejectedAt":{"type":"string","format":"date-time"},"commandId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}}},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"ApplicationReviewUpdateRequest":{"type":"object","minProperties":1,"properties":{"score":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Reviewer score (0–100). Omit to leave unchanged; null clears the score."},"reviewerNotes":{"type":["string","null"],"maxLength":5000,"description":"Internal reviewer notes. Omit to leave unchanged; null or empty string clears notes."}}},"ApplicationReviewUpdateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["submissionId","status","score","scoreUpdated","reviewerNotesUpdated","reviewedAt","commandId"],"properties":{"submissionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted","under_review"]},"score":{"type":["number","null"]},"scoreUpdated":{"type":"boolean"},"reviewerNotesUpdated":{"type":"boolean"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"commandId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"}}},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"IntegrationResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["application","workspace","environment","scopes","features","discord"],"properties":{"application":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"workspace":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"environment":{"type":"string","enum":["test","live"]},"scopes":{"type":"array","items":{"type":"string"}},"features":{"type":"object","additionalProperties":{"type":"boolean"}},"discord":{"type":"object","required":["connected"],"properties":{"connected":{"type":"boolean"},"guildId":{"type":["string","null"]},"status":{"type":["string","null"]},"connectedAt":{"type":["string","null"],"format":"date-time"}}}}},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"StaffMeResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":true},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"ActivityMeSummaryResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","additionalProperties":true},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}},"ActivityLeaderboardResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["entries"],"properties":{"entries":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"meta":{"type":"object","required":["requestId","correlationId"],"properties":{"requestId":{"type":"string"},"correlationId":{"type":"string"}}}}}},"parameters":{"CorrelationIdHeader":{"name":"X-Correlation-Id","in":"header","required":false,"description":"Optional client-supplied correlation ID. When absent, the gateway generates a request ID and returns it as X-Request-Id.","schema":{"type":"string"}},"RequestIdResponseHeader":{"name":"X-Request-Id","in":"header","required":true,"description":"Gateway request identifier.","schema":{"type":"string"}},"WorkspaceSelectorHeader":{"name":"X-Talqen-Workspace-Id","in":"header","required":false,"description":"Requested workspace selector only. Never treated as authorization. Future authenticated routes verify membership before trusting workspace context.","schema":{"type":"string"}},"IdempotencyKeyHeader":{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for accept requests. Reusing the same key with the same payload returns the original result.","schema":{"type":"string"}},"DiscordGuildIdHeader":{"name":"X-Discord-Guild-Id","in":"header","required":false,"description":"Discord guild ID consistency check for Talqen Connect. Never selects workspace scope.","schema":{"type":"string"}},"ActingDiscordUserIdHeader":{"name":"X-Acting-Discord-User-Id","in":"header","required":true,"description":"Discord user ID of the invoking staff member for self-service integration routes.","schema":{"type":"string"}}},"responses":{"ApiErrorResponse":{"description":"Standard API error.","headers":{"X-Request-Id":{"$ref":"#/components/parameters/RequestIdResponseHeader"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Dashboard user access token issued by Supabase Auth. API keys and other credential types are not yet available on this endpoint."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"session","description":"Placeholder for existing server-side dashboard sessions. Cross-subdomain cookies are not assumed as a permanent requirement."},"apiKeyAuth":{"type":"http","scheme":"bearer","description":"Scoped workspace API keys (talqen_test_... or talqen_live_...) created in the developer portal. Keys are bound to an approved developer application and workspace."},"discordServiceAuth":{"type":"http","scheme":"bearer","description":"Talqen Connect uses developer API keys (apiKeyAuth) with Discord guild and acting-user headers for self-service routes."},"robloxSignedRequest":{"type":"apiKey","in":"header","name":"X-Talqen-Signature","description":"Placeholder for Roblox HMAC-signed requests using X-Talqen-Key-Id, X-Talqen-Timestamp, X-Talqen-Nonce, and X-Talqen-Signature. Signature verification is separate from credential identity and idempotency."}}}}