@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Turso Platform API
@base https://api.turso.tech
@version 0.1.0
@auth Bearer bearer
@endpoints 46
@hint download_for_search
@toc organizations(41), locations(1), auth(4)

@group organizations
@endpoint GET /v1/organizations/{organizationSlug}/databases
@required {organizationSlug: str}
@optional {group: str, schema: str, parent: str}
@returns(200) {databases: [map]}

@endpoint POST /v1/organizations/{organizationSlug}/databases
@required {organizationSlug: str, name: str, group: str}
@optional {seed: map{type: str, name: str, timestamp: str}, size_limit: str, remote_encryption: map{encryption_key: str, encryption_cipher: str}}
@returns(200) {database: map{DbId: str, Hostname: str, Name: str}}
@errors {400, 409}

@endpoint GET /v1/organizations/{organizationSlug}/databases/{databaseName}
@required {organizationSlug: str, databaseName: str}
@returns(200) {database: map{Name: str, DbId: str, Hostname: str, block_reads: bool, block_writes: bool, regions: [str], primaryRegion: str, group: str, delete_protection: bool, parent: map?{id: str, name: str, branched_at: str(date-time)}}}
@errors {404}

@endpoint DELETE /v1/organizations/{organizationSlug}/databases/{databaseName}
@required {organizationSlug: str, databaseName: str}
@returns(200) {database: str}
@errors {404}

@endpoint GET /v1/organizations/{organizationSlug}/databases/{databaseName}/configuration
@required {organizationSlug: str, databaseName: str}
@returns(200) {size_limit: str, allow_attach: bool, block_reads: bool, block_writes: bool, delete_protection: bool}

@endpoint PATCH /v1/organizations/{organizationSlug}/databases/{databaseName}/configuration
@required {organizationSlug: str, databaseName: str}
@optional {size_limit: str, allow_attach: bool, block_reads: bool, block_writes: bool, delete_protection: bool}
@returns(200) {size_limit: str, allow_attach: bool, block_reads: bool, block_writes: bool, delete_protection: bool}

@endpoint GET /v1/organizations/{organizationSlug}/databases/{databaseName}/instances
@required {organizationSlug: str, databaseName: str}
@returns(200) {instances: [map]}

@endpoint GET /v1/organizations/{organizationSlug}/databases/{databaseName}/instances/{instanceName}
@required {organizationSlug: str, databaseName: str, instanceName: str}
@returns(200) {instance: map{uuid: str, name: str, type: str, region: str, hostname: str}}

@endpoint POST /v1/organizations/{organizationSlug}/databases/{databaseName}/auth/tokens
@required {organizationSlug: str, databaseName: str}
@optional {expiration: str=never, authorization: str(full-access/read-only)=full-access, permissions: map{read_attach: map}}
@returns(200) {jwt: str}
@errors {400, 404}

@endpoint GET /v1/organizations/{organizationSlug}/databases/{databaseName}/usage
@required {organizationSlug: str, databaseName: str}
@optional {from: str(date-time), to: str(date-time)}
@returns(200) {database: map{uuid: str, instances: [map], total: map{rows_read: int, rows_written: int, storage_bytes: int, bytes_synced: int}}}
@errors {400, 404}

@endpoint GET /v1/organizations/{organizationSlug}/databases/{databaseName}/stats
@required {organizationSlug: str, databaseName: str}
@returns(200) {top_queries: [map]?}
@errors {404}

@endpoint POST /v1/organizations/{organizationSlug}/databases/{databaseName}/auth/rotate
@required {organizationSlug: str, databaseName: str}
@returns(200)
@errors {404}

@endpoint GET /v1/organizations/{organizationSlug}/groups
@required {organizationSlug: str}
@returns(200) {groups: [any]}

@endpoint POST /v1/organizations/{organizationSlug}/groups
@required {organizationSlug: str, name: str, location: str}
@optional {extensions: any}
@returns(200) {group: any}
@errors {409}

@endpoint GET /v1/organizations/{organizationSlug}/groups/{groupName}
@required {organizationSlug: str, groupName: str}
@returns(200) {group: any}
@errors {404}

@endpoint DELETE /v1/organizations/{organizationSlug}/groups/{groupName}
@required {organizationSlug: str, groupName: str}
@returns(200) {group: any}
@errors {404}

@endpoint GET /v1/organizations/{organizationSlug}/groups/{groupName}/configuration
@required {organizationSlug: str, groupName: str}
@returns(200) {delete_protection: bool}

@endpoint PATCH /v1/organizations/{organizationSlug}/groups/{groupName}/configuration
@required {organizationSlug: str, groupName: str}
@optional {delete_protection: bool}
@returns(200) {delete_protection: bool}

@endpoint POST /v1/organizations/{organizationSlug}/groups/{groupName}/transfer
@required {organizationSlug: str, groupName: str}
@optional {organization: str}
@returns(200)
@errors {404}

@endpoint POST /v1/organizations/{organizationSlug}/groups/{groupName}/unarchive
@required {organizationSlug: str, groupName: str}
@returns(200) {group: any}
@errors {404}

@endpoint POST /v1/organizations/{organizationSlug}/groups/{groupName}/locations/{location}
@required {organizationSlug: str, groupName: str, location: str}
@returns(200) {group: any}
@errors {400, 404}

@endpoint DELETE /v1/organizations/{organizationSlug}/groups/{groupName}/locations/{location}
@required {organizationSlug: str, groupName: str, location: str}
@returns(200) {group: any}
@errors {400, 404}

@endpoint POST /v1/organizations/{organizationSlug}/groups/{groupName}/update
@required {organizationSlug: str, groupName: str}
@returns(200)
@errors {404}

@endpoint POST /v1/organizations/{organizationSlug}/groups/{groupName}/auth/tokens
@required {organizationSlug: str, groupName: str}
@optional {expiration: str=never, authorization: str(full-access/read-only)=full-access, permissions: map{read_attach: map}}
@returns(200) {jwt: str}
@errors {400, 404}

@endpoint POST /v1/organizations/{organizationSlug}/groups/{groupName}/auth/rotate
@required {organizationSlug: str, groupName: str}
@returns(200)
@errors {404}

@endgroup

@group locations
@endpoint GET /v1/locations
@returns(200) {locations: map}

@endgroup

@group organizations
@endpoint GET /v1/organizations
@returns(200)

@endpoint GET /v1/organizations/{organizationSlug}
@required {organizationSlug: str}
@returns(200) {organization: map{name: str, slug: str, type: str, overages: bool, blocked_reads: bool, blocked_writes: bool, plan_id: str, plan_timeline: str, platform: str}}
@errors {404}

@endpoint PATCH /v1/organizations/{organizationSlug}
@required {organizationSlug: str}
@optional {overages: bool}
@returns(200) {organization: map{name: str, slug: str, type: str, overages: bool, blocked_reads: bool, blocked_writes: bool, plan_id: str, plan_timeline: str, platform: str}}

@endpoint GET /v1/organizations/{organizationSlug}/plans
@required {organizationSlug: str}
@returns(200) {plans: [map]}

@endpoint GET /v1/organizations/{organizationSlug}/invoices
@required {organizationSlug: str}
@optional {type: str(all/upcoming/issued)}
@returns(200) {invoices: [map]}

@endpoint GET /v1/organizations/{organizationSlug}/subscription
@required {organizationSlug: str}
@returns(200) {subscription: map{name: str, overages: bool, plan: str, timeline: str}}

@endpoint GET /v1/organizations/{organizationSlug}/usage
@required {organizationSlug: str}
@returns(200) {organization: map{uuid: str, usage: map{rows_read: int, rows_written: int, databases: int, locations: int, storage_bytes: int, groups: int, bytes_synced: int}, databases: [map]}}

@endpoint GET /v1/organizations/{organizationSlug}/members
@required {organizationSlug: str}
@returns(200) {members: [map]}

@endpoint POST /v1/organizations/{organizationSlug}/members
@required {organizationSlug: str}
@optional {username: str, role: str(admin/member/viewer)=member}
@returns(200) {member: str, role: str}
@errors {404, 409}

@endpoint GET /v1/organizations/{organizationSlug}/members/{username}
@required {organizationSlug: str, username: str}
@returns(200) {member: map{username: str, role: str, email: str}}
@errors {404}

@endpoint PATCH /v1/organizations/{organizationSlug}/members/{username}
@required {organizationSlug: str, username: str, role: str(admin/member/viewer)}
@returns(200) {member: map{username: str, email: str, role: str}}
@errors {400, 403, 404}

@endpoint DELETE /v1/organizations/{organizationSlug}/members/{username}
@required {organizationSlug: str, username: str}
@returns(200) {member: str}
@errors {404}

@endpoint GET /v1/organizations/{organizationSlug}/invites
@required {organizationSlug: str}
@returns(200) {invites: [map]}

@endpoint POST /v1/organizations/{organizationSlug}/invites
@required {organizationSlug: str, email: str}
@optional {role: str(admin/member/viewer)=member}
@returns(200) {invited: map{ID: int, CreatedAt: str, UpdatedAt: str, DeletedAt: str, Role: str, Email: str, OrganizationID: int, Token: str, Organization: map{name: str, slug: str, type: str, overages: bool, blocked_reads: bool, blocked_writes: bool, plan_id: str, plan_timeline: str, platform: str}, Accepted: bool}}

@endpoint DELETE /v1/organizations/{organizationSlug}/invites/{email}
@required {organizationSlug: str, email: str}
@returns(200)
@errors {404}

@endgroup

@group auth
@endpoint GET /v1/auth/validate
@returns(200) {exp: int}

@endpoint GET /v1/auth/api-tokens
@returns(200) {tokens: [map]}

@endpoint POST /v1/auth/api-tokens/{tokenName}
@required {tokenName: str}
@optional {organization: str}
@returns(200) {name: str, id: str, token: str}

@endpoint DELETE /v1/auth/api-tokens/{tokenName}
@required {tokenName: str}
@returns(200) {token: str}

@endgroup

@group organizations
@endpoint GET /v1/organizations/{organizationSlug}/audit-logs
@required {organizationSlug: str}
@optional {page_size: int, page: int}
@returns(200) {audit_logs: [map], pagination: map{page: int, page_size: int, total_pages: int, total_rows: int}}

@endgroup

@end