> ## Documentation Index > Fetch the complete documentation index at: https://geckosecurity-docs-gitlab-service-account-identity.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Launch a scan > Starts a new scan for a GitLab repository that the team can access. This route requires a key whose role includes the `scans.run` permission, a configured team GitLab integration, and available scan capacity on the current plan. Gecko resolves the target branch in this order: request `branch`, branch in the GitLab URL, then the repository default branch. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/scans openapi: 3.1.0 info: title: Gecko SAST Scanner API version: v1 description: >- Use the Gecko API to launch scans and read scan, repository, and vulnerability data for your active team. servers: - url: https://app.gecko.security description: Production security: - ApiKeyAuth: [] tags: - name: Scans description: Launch scans and read scan-level data. - name: Repositories description: Read repository inventory and repository vulnerability data. - name: Vulnerabilities description: Read vulnerability data across your active team. - name: Utility description: Service health and utility endpoints. paths: /api/v1/scans: post: tags: - Scans summary: Launch a scan description: >- Starts a new scan for a GitLab repository that the team can access. This route requires a key whose role includes the `scans.run` permission, a configured team GitLab integration, and available scan capacity on the current plan. Gecko resolves the target branch in this order: request `branch`, branch in the GitLab URL, then the repository default branch. operationId: postApiV1Scans requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScanCreateRequest' example: name: Paperbaum gitlabUrl: https://gitlab.com/gecko-security/Paperbaum/-/tree/main responses: '201': description: The scan was launched. headers: X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ScanCreateResponse' example: version: v1 data: scanId: f5d35de5-8fc8-4a01-8e28-3bae5d6d26ad name: Paperbaum status: launched repository: fullName: gecko-security/Paperbaum branch: main instance: gitlab.com taskArn: >- arn:aws:ecs:eu-west-2:123456789012:task/gecko/1234567890abcdef '400': description: The request body or GitLab URL is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingFields: value: error: '''name'' and ''gitlabUrl'' are required' instanceMismatch: value: error: GitLab instance mismatch details: Expected gitlab.com, received self-managed.example.com '401': $ref: '#/components/responses/UnauthorizedError' '403': description: >- The API key does not have permission to run scans, the key is not attached to a team, the team GitLab integration is unavailable, or the plan scan limit was reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingPermission: value: error: API key lacks scans.run permission noTeam: value: error: No active team associated with API key gitlabMissing: value: error: GitLab integration not configured for team '404': description: The team for the API key could not be found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Team not found '429': $ref: '#/components/responses/RateLimitedError' '500': $ref: '#/components/responses/InternalServerError' '502': description: Gecko created the scan record, but the scanner launch failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Failed to start scan details: scanner service unavailable components: schemas: ScanCreateRequest: type: object required: - name - gitlabUrl properties: name: type: string description: Readable scan name. gitlabUrl: type: string format: uri description: >- GitLab repository URL. You can include a branch in `?ref=` or in a `/-/tree/` path. branch: type: string description: Optional branch override. ScanCreateResponse: type: object required: - version - data properties: version: type: string const: v1 data: type: object required: - scanId - name - status - repository - taskArn properties: scanId: type: string format: uuid name: type: string status: type: string const: launched repository: type: object required: - fullName - branch - instance properties: fullName: type: string branch: type: - string - 'null' instance: type: string taskArn: type: - string - 'null' ErrorResponse: type: object required: - error properties: error: type: string details: type: - string - 'null' hint: type: - string - 'null' headers: XRateLimitRemaining: description: Requests remaining in the current one-hour window for the API key. schema: type: integer XRateLimitReset: description: >- ISO 8601 timestamp for when the current one-hour rate-limit window resets. schema: type: string format: date-time RetryAfter: description: Seconds to wait before retrying the request. schema: type: integer responses: UnauthorizedError: description: The API key is missing, malformed, or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingKey: value: error: API key is required badFormat: value: error: Invalid API key format badKey: value: error: Invalid API key RateLimitedError: description: The API key reached the per-hour request limit. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Rate limit exceeded InternalServerError: description: Gecko failed to process the request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Internal server error securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Team-scoped Gecko API key. Keys start with `gk_`. ````