@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Val Town API
@base https://api.val.town
@version 1
@auth Bearer bearer
@endpoints 36
@hint download_for_search
@toc alias(2), me(2), blob(4), users(1), sqlite(2), email(1), telemetry(2), vals(17), files(1), orgs(2), connections(2)

@group alias
@endpoint GET /v1/alias/{username}
@required {username: str}
@returns(200) {id: str(uuid), type: any, bio: any, username: any, profileImageUrl: any, url: str(uri), links: map{self: str(uri)}}

@endgroup

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

@endgroup

@group blob
@endpoint GET /v1/blob
@optional {prefix: str}
@returns(200)

@endpoint GET /v1/blob/{key}
@required {key: str}
@returns(200)

@endpoint POST /v1/blob/{key}
@required {key: str}
@returns(201)
@errors {400}

@endpoint DELETE /v1/blob/{key}
@required {key: str}
@returns(204)

@endgroup

@group users
@endpoint GET /v1/users/{user_id}
@required {user_id: str(uuid)}
@returns(200) {id: str(uuid), type: any, bio: any, username: any, profileImageUrl: any, url: str(uri), links: map{self: str(uri)}}

@endgroup

@group sqlite
@endpoint POST /v1/sqlite/execute
@required {statement: any}
@returns(200) {columns: [str], columnTypes: [str], rows: [[any]], rowsAffected: num, lastInsertRowid: any}

@endpoint POST /v1/sqlite/batch
@required {statements: [any]}
@optional {mode: any(write/read/deferred)}
@returns(200)

@endgroup

@group email
@endpoint POST /v1/email
@optional {subject: str, from: any, headers: map, to: any, cc: any, bcc: any, text: str, html: str, attachments: [map{content!: str, filename!: str, type: str, disposition: str, contentId: str}], replyToList: any}
@returns(202) {message: str}
@errors {500}

@endgroup

@group telemetry
@endpoint GET /v1/telemetry/traces
@required {direction: any(asc/desc)=desc, limit: int=20}
@optional {file_id: str(uuid), branch_ids: [str(uuid)], start: str(date-time), end: str(date-time), order_by: any(start_time/end_time)=start_time}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endpoint GET /v1/telemetry/logs
@required {direction: any(asc/desc)=desc, limit: int=20}
@optional {trace_ids: [str], file_id: str(uuid), branch_ids: [str(uuid)], start: str(date-time), end: str(date-time)}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endgroup

@group vals
@endpoint GET /v2/vals/{val_id}
@required {val_id: str(uuid)}
@returns(200) {name: str, id: str(uuid), createdAt: str(date-time), privacy: any, author: map{type: any, id: str(uuid), username: any}, imageUrl: any, description: any, links: map{self: str(uri), html: str(uri)}}

@endpoint DELETE /v2/vals/{val_id}
@required {val_id: str(uuid)}
@returns(204)
@errors {404}

@endpoint GET /v2/vals
@required {limit: int=20}
@optional {privacy: any(public/unlisted/private), user_id: str(uuid), cursor: str(date-time)}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endpoint POST /v2/vals
@required {name: str, privacy: any(public/unlisted/private)}
@optional {description: str, orgId: str(uuid)}
@returns(201) {name: str, id: str(uuid), createdAt: str(date-time), privacy: any, author: map{type: any, id: str(uuid), username: any}, imageUrl: any, description: any, links: map{self: str(uri), html: str(uri)}}
@errors {409}

@endpoint GET /v2/vals/{val_id}/branches/{branch_id}
@required {val_id: str(uuid), branch_id: str(uuid)}
@returns(200) {name: str, id: str(uuid), version: int, createdAt: str(date-time), updatedAt: str(date-time), forkedBranchId: any, links: map{self: str(uri), html: str(uri)}}

@endpoint DELETE /v2/vals/{val_id}/branches/{branch_id}
@required {val_id: str(uuid), branch_id: str(uuid)}
@returns(204)
@errors {404}

@endpoint GET /v2/vals/{val_id}/branches
@required {offset: int=0, limit: int=20, val_id: str(uuid)}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endpoint POST /v2/vals/{val_id}/branches
@required {val_id: str(uuid), name: str}
@optional {branchId: str(uuid)}
@returns(201) {name: str, id: str(uuid), version: int, createdAt: str(date-time), updatedAt: str(date-time), forkedBranchId: any, links: map{self: str(uri), html: str(uri)}}
@errors {409}

@endpoint GET /v2/vals/{val_id}/files
@required {path: str, recursive: bool=false, offset: int=0, limit: int=20, val_id: str(uuid)}
@optional {version: int, branch_id: str(uuid)}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endpoint POST /v2/vals/{val_id}/files
@required {path: str, val_id: str(uuid)}
@optional {branch_id: str(uuid)}
@returns(201) {name: str, id: str(uuid), path: str, version: int, updatedAt: str(date-time), type: any, links: map{self: str(uri), html: str(uri), module: str(uri), endpoint: str(uri), email: str(email)}}
@errors {409}

@endpoint DELETE /v2/vals/{val_id}/files
@required {path: str, recursive: bool=false, val_id: str(uuid)}
@optional {branch_id: str(uuid)}
@returns(204)
@errors {404}

@endpoint PUT /v2/vals/{val_id}/files
@required {path: str, val_id: str(uuid)}
@optional {branch_id: str(uuid)}
@returns(200) {name: str, id: str(uuid), path: str, version: int, updatedAt: str(date-time), type: any, links: map{self: str(uri), html: str(uri), module: str(uri), endpoint: str(uri), email: str(email)}}
@returns(201) {name: str, id: str(uuid), path: str, version: int, updatedAt: str(date-time), type: any, links: map{self: str(uri), html: str(uri), module: str(uri), endpoint: str(uri), email: str(email)}}

@endpoint GET /v2/vals/{val_id}/environment_variables
@required {offset: int=0, limit: int=20, val_id: str(uuid)}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endpoint POST /v2/vals/{val_id}/environment_variables
@required {val_id: str(uuid), value: str, key: str}
@optional {description: str}
@returns(201) {key: str, description: any, updatedAt: any, createdAt: str(date-time)}
@errors {409}

@endpoint PUT /v2/vals/{val_id}/environment_variables/{key}
@required {val_id: str(uuid), key: str, value: str}
@optional {description: str}
@returns(201) {key: str, description: any, updatedAt: any, createdAt: str(date-time)}

@endpoint DELETE /v2/vals/{val_id}/environment_variables/{key}
@required {val_id: str(uuid), key: str}
@returns(204)
@errors {404}

@endpoint GET /v2/vals/{val_id}/files/content
@required {path: str, val_id: str(uuid)}
@optional {version: int, branch_id: str(uuid), If-Match: str, If-Unmodified-Since: str, If-None-Match: str, If-Modified-Since: str, Cache-Control: str}
@returns(200)
@errors {304, 412}

@endgroup

@group files
@endpoint GET /v2/files/{file_id}
@required {file_id: str(uuid)}
@returns(200) {name: str, id: str(uuid), path: str, version: int, updatedAt: str(date-time), type: any, links: map{self: str(uri), html: str(uri), module: str(uri), endpoint: str(uri), email: str(email)}}

@endgroup

@group alias
@endpoint GET /v2/alias/vals/{username}/{val_name}
@required {username: str, val_name: str}
@returns(200) {name: str, id: str(uuid), createdAt: str(date-time), privacy: any, author: map{type: any, id: str(uuid), username: any}, imageUrl: any, description: any, links: map{self: str(uri), html: str(uri)}}

@endgroup

@group me
@endpoint GET /v2/me/vals
@required {offset: int=0, limit: int=20}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endgroup

@group orgs
@endpoint GET /v2/orgs
@required {offset: int=0, limit: int=20}
@returns(200) {data: [map], links: map{self: str(uri), prev: str(uri), next: str(uri)}}

@endpoint GET /v2/orgs/{org_id}/memberships
@required {org_id: str(uuid)}
@returns(200)

@endgroup

@group connections
@endpoint POST /v3/connections/slack/token
@required {team_id: str}
@returns(200) {access_token: str}
@errors {403, 404, 500}

@endpoint POST /v3/connections/google-docs/token
@required {email: str}
@returns(200) {access_token: str, granted_scopes: [str]}
@errors {403, 404, 500}

@endgroup

@end