> ## Documentation Index > Fetch the complete documentation index at: https://docs.listenlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Launch Study > Publish a draft study and get its self-recruit link ## OpenAPI ````yaml api-v2/openapi.yaml POST /api/public/v1/studies/{studyId}/launch openapi: 3.0.3 info: title: Listen Labs Public API v2 version: 2.0.0 description: >- Create and launch studies, and retrieve response data programmatically. Authenticated with an `x-api-key` header; the key is scoped to a single organization. Cross-field rules that JSON Schema cannot express (screening placement, min/maxSelect coupling, unique externalIds, reference resolution, exclusiveOption placement) are described on the relevant schemas and enforced by the server (returned as 400 responses). All error responses share one JSON envelope: `error` (human-readable message, may change) and `code` (stable machine-readable identifier; branch on this). 400 responses may also carry `issues` with per-field schema violations. The possible codes for each response are listed in its description. servers: - url: https://listenlabs.ai description: Production security: - ApiKeyAuth: [] paths: /api/public/v1/studies/{studyId}/launch: post: summary: Launch a draft and return the self-recruit link description: >- Publishes the draft and opens its self-recruit link. Requires the key's user to have StartRecruitment on the study. Project responses bill to the launch wallet: pass walletId, or omit the body to auto-select the organization's wallet when it has exactly one. operationId: launchStudy parameters: - name: studyId in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/LaunchRequest' responses: '200': description: Launched content: application/json: schema: $ref: '#/components/schemas/LaunchResponse' '400': description: >- Invalid body, the organization has multiple wallets and walletId was omitted, or the wallet cannot fund the launch (insufficient balance or grant limit). Codes: `invalid_json`, `invalid_request_body`, `wallet_required`, `insufficient_credits`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' examples: invalidJson: value: error: Invalid JSON body code: invalid_json invalidRequestBody: value: error: Invalid request body code: invalid_request_body issues: - code: invalid_type expected: string received: number path: - walletId message: Expected string, received number walletRequired: value: error: >- Multiple wallets are available to this organization; pass walletId in the request body (see GET /api/public/v1/wallets) code: wallet_required insufficientCredits: value: error: Insufficient balance code: insufficient_credits '401': $ref: '#/components/responses/Unauthorized' '403': description: >- No permission to launch this study, or no access to the specified wallet. Codes: `launch_permission_denied`, `wallet_access_denied`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: launchPermissionDenied: value: error: No permission to launch this study code: launch_permission_denied walletAccessDenied: value: error: No access to the specified wallet code: wallet_access_denied '404': description: 'Study not found in the key''s org. Codes: `study_not_found`.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: studyNotFound: value: error: Study not found code: study_not_found '409': description: >- The study is busy (an update is in flight) or the publish raced a concurrent edit. Codes: `study_busy`, `conflict`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: studyBusy: value: error: Study is currently being updated. Try again in a moment. code: study_busy publishRace: value: error: >- Revision is no longer a dev revision. Please refresh and try again. code: conflict '500': $ref: '#/components/responses/ServerError' components: schemas: LaunchRequest: type: object properties: walletId: type: string format: uuid description: >- Wallet to bill this study from; must be granted to the API key's organization (see GET /api/public/v1/wallets). Omit to auto-select the organization's wallet when it has exactly one. additionalProperties: false description: Optional body; omit it entirely to auto-select the wallet. LaunchResponse: type: object properties: id: type: string format: uuid linkId: type: string selfRecruitLink: type: string format: uri status: type: string enum: - live wallet: allOf: - $ref: '#/components/schemas/Wallet' description: >- The wallet this launch is billed to. Omitted when no wallet is bound (organization without wallet billing). required: - id - linkId - selfRecruitLink - status additionalProperties: false ValidationError: type: object properties: error: type: string description: Human-readable description of the failure. code: type: string enum: - invalid_json - invalid_request_body - invalid_study_guide - wallet_required - insufficient_credits - bad_request - missing_api_key - invalid_api_key - unauthorized - launch_permission_denied - wallet_access_denied - forbidden - study_not_found - response_not_found - not_found - study_busy - concurrent_modification - conflict - internal_error description: >- Stable machine-readable error code. Branch on this, not on the `error` text, which may change. issues: type: array items: type: object additionalProperties: {} description: >- Present when code is `invalid_request_body`: the schema violations (Zod issues), each with a `path` and `message`. required: - error - code additionalProperties: false Error: type: object properties: error: type: string description: Human-readable description of the failure. code: type: string enum: - invalid_json - invalid_request_body - invalid_study_guide - wallet_required - insufficient_credits - bad_request - missing_api_key - invalid_api_key - unauthorized - launch_permission_denied - wallet_access_denied - forbidden - study_not_found - response_not_found - not_found - study_busy - concurrent_modification - conflict - internal_error description: >- Stable machine-readable error code. Branch on this, not on the `error` text, which may change. required: - error - code additionalProperties: false Wallet: type: object properties: walletId: type: string format: uuid name: type: string recruitmentCreditBalance: $ref: '#/components/schemas/CreditBalance' projectCreditBalance: $ref: '#/components/schemas/CreditBalance' required: - walletId - name - recruitmentCreditBalance - projectCreditBalance additionalProperties: false CreditBalance: type: object properties: balance: type: number description: Credits currently available to spend. usage: type: number description: Credits already used by this organization, including active holds. required: - balance - usage additionalProperties: false responses: Unauthorized: description: 'Missing or invalid API key. Codes: `missing_api_key`, `invalid_api_key`.' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingApiKey: value: error: Missing x-api-key header code: missing_api_key invalidApiKey: value: error: Invalid API key code: invalid_api_key ServerError: description: >- Internal error (details are logged server-side, not returned). Codes: `internal_error`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internalError: value: error: Internal server error code: internal_error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````