openapi: 3.1.0 info: title: Alconost Human API version: 1.0.0 servers: - url: https://hitl.alconost.com/api description: Alconost Human paths: /v1/files: post: tags: - alconost.human.v1.FileService summary: CreateFile description: Upload a file to storage. operationId: FileService_CreateFile requestBody: content: application/json: schema: title: file $ref: '#/components/schemas/google.api.HttpBody' responses: "200": description: Success content: application/json: schema: $ref: '#/components/schemas/alconost.human.v1.CreateFileResponse' /v1/files/{id}: get: tags: - alconost.human.v1.FileService summary: GetFile description: Download a file's bytes, or the byte range selected by range. operationId: FileService_GetFile parameters: - name: id in: path required: true schema: type: string title: id - name: range in: query description: |- Inclusive byte range, as in an HTTP Range header without the "bytes=" unit: "0-499" (first 500 bytes), "500-" (byte 500 to the end) or "-500" (last 500 bytes). Unset returns the whole file. schema: type: string title: range pattern: ^([0-9]+-[0-9]*|-[0-9]+)$ description: |- Inclusive byte range, as in an HTTP Range header without the "bytes=" unit: "0-499" (first 500 bytes), "500-" (byte 500 to the end) or "-500" (last 500 bytes). Unset returns the whole file. responses: "200": description: Success content: application/json: schema: title: file $ref: '#/components/schemas/google.api.HttpBody' delete: tags: - alconost.human.v1.FileService summary: DeleteFile description: Delete a file. Only the owner can delete. operationId: FileService_DeleteFile parameters: - name: id in: path required: true schema: type: string title: id responses: "200": description: Success content: application/json: schema: $ref: '#/components/schemas/alconost.human.v1.DeleteFileResponse' /v1/tasks: get: tags: - alconost.human.v1.TaskService summary: ListTasks description: List tasks, newest first, optionally in one status. operationId: TaskService_ListTasks parameters: - name: status in: query description: Only tasks in this status. Unset = every status. schema: type: string title: status enum: - new - estimated - queued - in_progress - done - declined - canceled - expired description: Only tasks in this status. Unset = every status. - name: limit in: query description: Max rows. Unset = 100. schema: type: integer title: limit maximum: 250 minimum: 1 format: int32 description: Max rows. Unset = 100. - name: after in: query description: 'Keyset cursor: id of the last row from the previous page.' schema: type: string title: after format: uuid description: 'Keyset cursor: id of the last row from the previous page.' responses: "200": description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/alconost.human.v1.Task' title: tasks post: tags: - alconost.human.v1.TaskService summary: CreateTask description: Create a task for a human to review. operationId: TaskService_CreateTask requestBody: content: application/json: schema: $ref: '#/components/schemas/alconost.human.v1.CreateTaskRequest' required: true responses: "200": description: Success content: application/json: schema: title: task $ref: '#/components/schemas/alconost.human.v1.Task' /v1/tasks/{id}: get: tags: - alconost.human.v1.TaskService summary: GetTask description: Fetch one task by id; poll until the status is terminal. operationId: TaskService_GetTask parameters: - name: id in: path required: true schema: type: string title: id format: uuid responses: "200": description: Success content: application/json: schema: title: task $ref: '#/components/schemas/alconost.human.v1.Task' patch: tags: - alconost.human.v1.TaskService summary: UpdateTask description: |- Amend an open task, e.g. attachments that finished rendering after create. Fails if already terminal. Unset fields are left unchanged. Once a "new" task has an assignee, a price and an estimate it moves to "estimated". The price can still change while "estimated". operationId: TaskService_UpdateTask parameters: - name: id in: path required: true schema: type: string title: id format: uuid requestBody: content: application/json: schema: type: object properties: title: type: - string - "null" title: title maxLength: 200 minLength: 1 detail: type: - string - "null" title: detail maxLength: 4000 context: type: object title: context maxProperties: 32 additionalProperties: type: string title: value maxLength: 1024 estimate: type: - string - "null" title: estimate maxLength: 4000 minLength: 1 description: Markdown. price: type: - integer - string - "null" title: price minimum: 0 format: int64 description: USD cents. attachments: type: array items: $ref: '#/components/schemas/alconost.human.v1.Attachment' title: attachments maxItems: 16 assignee_id: type: - string - "null" title: assignee_id maxLength: 64 minLength: 1 description: The assignee's User.id (UserService.ListUsers). title: UpdateTaskRequest additionalProperties: false description: |- Amends an open task. Fields left unset keep their current value; context and attachments, when present, replace the stored value wholesale. An empty map/list means "unchanged" — cancel and re-create to drop them. required: true responses: "200": description: Success content: application/json: schema: title: task $ref: '#/components/schemas/alconost.human.v1.Task' /v1/tasks/{id}/accept: post: tags: - alconost.human.v1.TaskService summary: AcceptTask description: |- Accept the price of an "estimated" task, sending it to the assignee as "queued". Only the task's creator may accept, with the price it read; if the price has changed since, it fails with ABORTED: read it again. operationId: TaskService_AcceptTask parameters: - name: id in: path required: true schema: type: string title: id format: uuid requestBody: content: application/json: schema: type: object properties: price: type: - integer - string - "null" title: price minimum: 0 format: int64 description: The price the creator read (USD cents). Must match the current price. title: AcceptTaskRequest required: - price additionalProperties: false required: true responses: "200": description: Success content: application/json: schema: title: task $ref: '#/components/schemas/alconost.human.v1.Task' /v1/tasks/{id}/cancel: post: tags: - alconost.human.v1.TaskService summary: CancelTask description: |- Withdraw a task. No-op if already terminal. Only the task's creator may cancel it (any key, for tasks created before creators were recorded). operationId: TaskService_CancelTask parameters: - name: id in: path required: true schema: type: string title: id format: uuid responses: "200": description: Success content: application/json: schema: $ref: '#/components/schemas/alconost.human.v1.CancelTaskResponse' /v1/tasks/{id}/decline: post: tags: - alconost.human.v1.TaskService summary: DeclineTask description: |- Decline the price of an "estimated" task, ending it as "declined". Only the task's creator may decline. operationId: TaskService_DeclineTask parameters: - name: id in: path required: true schema: type: string title: id format: uuid responses: "200": description: Success content: application/json: schema: title: task $ref: '#/components/schemas/alconost.human.v1.Task' /v1/tasks/{id}/resolve: post: tags: - alconost.human.v1.TaskService summary: ResolveTask description: |- Give the result, moving a "queued" or "in_progress" task to "done". The result must match the task's type. Only API keys of the task's assignee may resolve it; assignees normally do so on the dashboard. operationId: TaskService_ResolveTask parameters: - name: id in: path required: true schema: type: string title: id format: uuid requestBody: content: application/json: schema: type: object allOf: - {} - oneOf: - type: object properties: review: title: review $ref: '#/components/schemas/alconost.human.v1.ReviewResult' title: review required: - review title: ResolveTaskRequest additionalProperties: false required: true responses: "200": description: Success content: application/json: schema: $ref: '#/components/schemas/alconost.human.v1.ResolveTaskResponse' /v1/users: get: tags: - alconost.human.v1.UserService summary: ListUsers description: List users by email. Disabled users are left out. operationId: UserService_ListUsers parameters: - name: role in: query description: Only users with this role. Unset = everyone. schema: type: string title: role enum: - reviewer - admin description: Only users with this role. Unset = everyone. responses: "200": description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/alconost.human.v1.User' title: users components: schemas: alconost.human.v1.AcceptTaskRequest: type: object properties: id: type: string title: id format: uuid price: type: - integer - string - "null" title: price minimum: 0 format: int64 description: The price the creator read (USD cents). Must match the current price. title: AcceptTaskRequest required: - price additionalProperties: false alconost.human.v1.AcceptTaskResponse: type: object properties: task: title: task $ref: '#/components/schemas/alconost.human.v1.Task' title: AcceptTaskResponse additionalProperties: false alconost.human.v1.Attachment: type: object properties: file_id: type: string title: file_id maxLength: 64 minLength: 1 label: type: string title: label maxLength: 200 description: Human label, e.g. "source (en)" or "target (ja)". title: Attachment additionalProperties: false description: |- Attachment references a file uploaded via FileService. The server resolves its content type; the dashboard renders a player/preview accordingly. alconost.human.v1.CancelTaskRequest: type: object properties: id: type: string title: id format: uuid title: CancelTaskRequest additionalProperties: false alconost.human.v1.CancelTaskResponse: type: object title: CancelTaskResponse additionalProperties: false description: 'Empty: re-fetch with GetTask if the canceled state is needed.' alconost.human.v1.CreateFileRequest: type: object properties: file: title: file $ref: '#/components/schemas/google.api.HttpBody' title: CreateFileRequest required: - file additionalProperties: false alconost.human.v1.CreateFileResponse: type: object properties: id: type: string title: id title: CreateFileResponse required: - id additionalProperties: false alconost.human.v1.CreateTaskRequest: type: object properties: type: type: - string - "null" title: type enum: - review description: The task's type. Unset = "review". title: type: string title: title maxLength: 200 minLength: 1 detail: type: string title: detail maxLength: 4000 context: type: object title: context maxProperties: 32 additionalProperties: type: string title: value maxLength: 1024 attachments: type: array items: $ref: '#/components/schemas/alconost.human.v1.Attachment' title: attachments maxItems: 16 title: CreateTaskRequest additionalProperties: false alconost.human.v1.CreateTaskRequest.ContextEntry: type: object properties: key: type: string title: key value: type: string title: value title: ContextEntry additionalProperties: false alconost.human.v1.CreateTaskResponse: type: object properties: task: title: task $ref: '#/components/schemas/alconost.human.v1.Task' title: CreateTaskResponse additionalProperties: false alconost.human.v1.DeclineTaskRequest: type: object properties: id: type: string title: id format: uuid title: DeclineTaskRequest additionalProperties: false alconost.human.v1.DeclineTaskResponse: type: object properties: task: title: task $ref: '#/components/schemas/alconost.human.v1.Task' title: DeclineTaskResponse additionalProperties: false alconost.human.v1.DeleteFileRequest: type: object properties: id: type: string title: id title: DeleteFileRequest required: - id additionalProperties: false alconost.human.v1.DeleteFileResponse: type: object title: DeleteFileResponse additionalProperties: false alconost.human.v1.GetFileRequest: type: object properties: id: type: string title: id range: type: string title: range pattern: ^([0-9]+-[0-9]*|-[0-9]+)$ description: |- Inclusive byte range, as in an HTTP Range header without the "bytes=" unit: "0-499" (first 500 bytes), "500-" (byte 500 to the end) or "-500" (last 500 bytes). Unset returns the whole file. title: GetFileRequest required: - id additionalProperties: false alconost.human.v1.GetFileResponse: type: object properties: file: title: file $ref: '#/components/schemas/google.api.HttpBody' title: GetFileResponse additionalProperties: false alconost.human.v1.GetTaskRequest: type: object properties: id: type: string title: id format: uuid title: GetTaskRequest additionalProperties: false alconost.human.v1.GetTaskResponse: type: object properties: task: title: task $ref: '#/components/schemas/alconost.human.v1.Task' title: GetTaskResponse additionalProperties: false alconost.human.v1.ListTasksRequest: type: object properties: status: type: - string - "null" title: status enum: - new - estimated - queued - in_progress - done - declined - canceled - expired description: Only tasks in this status. Unset = every status. limit: type: - integer - "null" title: limit maximum: 250 minimum: 1 format: int32 description: Max rows. Unset = 100. after: type: - string - "null" title: after format: uuid description: 'Keyset cursor: id of the last row from the previous page.' title: ListTasksRequest additionalProperties: false alconost.human.v1.ListTasksResponse: type: object properties: tasks: type: array items: $ref: '#/components/schemas/alconost.human.v1.Task' title: tasks title: ListTasksResponse additionalProperties: false alconost.human.v1.ListUsersRequest: type: object properties: role: type: - string - "null" title: role enum: - reviewer - admin description: Only users with this role. Unset = everyone. title: ListUsersRequest additionalProperties: false alconost.human.v1.ListUsersResponse: type: object properties: users: type: array items: $ref: '#/components/schemas/alconost.human.v1.User' title: users title: ListUsersResponse additionalProperties: false alconost.human.v1.ResolveTaskRequest: type: object allOf: - properties: id: type: string title: id format: uuid - oneOf: - type: object properties: review: title: review $ref: '#/components/schemas/alconost.human.v1.ReviewResult' title: review required: - review title: ResolveTaskRequest additionalProperties: false alconost.human.v1.ResolveTaskResponse: type: object title: ResolveTaskResponse additionalProperties: false description: 'Empty: re-fetch with GetTask if the resolved state is needed.' alconost.human.v1.ReviewResult: type: object properties: verdict: type: string title: verdict enum: - approved - rejected notes: type: - string - "null" title: notes maxLength: 8000 description: 'Free-form Markdown: the reviewer''s notes, e.g. timestamped.' title: ReviewResult additionalProperties: false description: The result of a "review" task. alconost.human.v1.Task: type: object allOf: - properties: id: type: string title: id format: uuid description: Server-assigned, opaque. Used for polling. UUIDv7 (creation-ordered). type: type: string title: type enum: - review description: |- What kind of work it is, which decides the shape of its result. Only "review" so far. status: type: string title: status enum: - new - estimated - queued - in_progress - done - declined - canceled - expired title: type: string title: title maxLength: 200 minLength: 1 description: One-line ask. Required. e.g. "English to Spanish translation". detail: type: string title: detail maxLength: 4000 description: Optional longer detail for the human. context: type: object title: context maxProperties: 32 additionalProperties: type: string title: value maxLength: 1024 description: Optional key/values for display and caller correlation. attachments: type: array items: $ref: '#/components/schemas/alconost.human.v1.Attachment' title: attachments description: Content for the assignee to inspect (e.g. source + translated videos). estimate: type: - string - "null" title: estimate maxLength: 4000 description: |- Free-form Markdown: how the price was reached, e.g. "1.5h × $10/h, 12 min of video". Set on every task from "estimated" on. price: type: - integer - string - "null" title: price minimum: 0 format: int64 description: Pay for this task, in USD cents (1500 = $15.00). creator: title: creator description: |- The user whose API key created this task. Unset for tasks created before it was recorded. $ref: '#/components/schemas/alconost.human.v1.UserRef' assignee: title: assignee description: |- The one dashboard user who does this task: a reviewer or an admin (UserService.ListUsers). Only they and admins see it. Set on every task from "estimated" on. $ref: '#/components/schemas/alconost.human.v1.UserRef' created_at: title: created_at $ref: '#/components/schemas/google.protobuf.Timestamp' estimated_at: title: estimated_at description: 'First priced: moved from "new" to "estimated".' $ref: '#/components/schemas/google.protobuf.Timestamp' accepted_at: title: accepted_at description: 'The creator accepted the price: moved to "queued".' $ref: '#/components/schemas/google.protobuf.Timestamp' started_at: title: started_at description: 'The assignee first opened it: moved to "in_progress".' $ref: '#/components/schemas/google.protobuf.Timestamp' done_at: title: done_at description: Each set when the task ends that way. "expired" via server TTL. $ref: '#/components/schemas/google.protobuf.Timestamp' declined_at: title: declined_at $ref: '#/components/schemas/google.protobuf.Timestamp' canceled_at: title: canceled_at $ref: '#/components/schemas/google.protobuf.Timestamp' expired_at: title: expired_at $ref: '#/components/schemas/google.protobuf.Timestamp' - oneOf: - type: object properties: review: title: review $ref: '#/components/schemas/alconost.human.v1.ReviewResult' title: review required: - review title: Task additionalProperties: false description: Work for a human. alconost.human.v1.Task.ContextEntry: type: object properties: key: type: string title: key value: type: string title: value title: ContextEntry additionalProperties: false alconost.human.v1.UpdateTaskRequest: type: object properties: id: type: string title: id format: uuid title: type: - string - "null" title: title maxLength: 200 minLength: 1 detail: type: - string - "null" title: detail maxLength: 4000 context: type: object title: context maxProperties: 32 additionalProperties: type: string title: value maxLength: 1024 estimate: type: - string - "null" title: estimate maxLength: 4000 minLength: 1 description: Markdown. price: type: - integer - string - "null" title: price minimum: 0 format: int64 description: USD cents. attachments: type: array items: $ref: '#/components/schemas/alconost.human.v1.Attachment' title: attachments maxItems: 16 assignee_id: type: - string - "null" title: assignee_id maxLength: 64 minLength: 1 description: The assignee's User.id (UserService.ListUsers). title: UpdateTaskRequest additionalProperties: false description: |- Amends an open task. Fields left unset keep their current value; context and attachments, when present, replace the stored value wholesale. An empty map/list means "unchanged" — cancel and re-create to drop them. alconost.human.v1.UpdateTaskRequest.ContextEntry: type: object properties: key: type: string title: key value: type: string title: value title: ContextEntry additionalProperties: false alconost.human.v1.UpdateTaskResponse: type: object properties: task: title: task $ref: '#/components/schemas/alconost.human.v1.Task' title: UpdateTaskResponse additionalProperties: false alconost.human.v1.User: type: object properties: id: type: string title: id description: Server-assigned, opaque. slug: type: string title: slug description: |- Short unique handle, the same as their alpha staff id; empty when not set. Estimators link users to alpha by it, falling back to email. email: type: string title: email name: type: string title: name description: Set by an admin, or from Google on first sign-in. avatar_url: type: string title: avatar_url description: Google profile picture URL; empty until they sign in. role: type: string title: role enum: - reviewer - admin description: |- "reviewer": sees the tasks assigned to them. "admin": sees and manages everything. description: type: string title: description description: |- Free text set by admins: languages, skills, customers. Estimators read it when picking a reviewer. title: User additionalProperties: false alconost.human.v1.UserRef: type: object properties: id: type: string title: id description: 'Stable: compare on this. The same as User.id.' slug: type: string title: slug description: For display; can change. Empty when not set. title: UserRef additionalProperties: false description: A user referenced from a task. google.api.HttpBody: type: object properties: content_type: type: string title: content_type description: The HTTP Content-Type header value specifying the content type of the body. data: type: string title: data format: byte description: The HTTP request/response body as raw binary. extensions: type: array items: $ref: '#/components/schemas/google.protobuf.Any' title: extensions description: |- Application specific response metadata. Must be set in the first response for streaming APIs. title: HttpBody additionalProperties: false description: |- Message that represents an arbitrary HTTP body. It should only be used for payload formats that can't be represented as JSON, such as raw binary or an HTML page. This message can be used both in streaming and non-streaming API methods in the request as well as the response. It can be used as a top-level request field, which is convenient if one wants to extract parameters from either the URL or HTTP template into the request fields and also want access to the raw HTTP body. Example: message GetResourceRequest { // A unique request id. string request_id = 1; // The raw HTTP body is bound to this field. google.api.HttpBody http_body = 2; } service ResourceService { rpc GetResource(GetResourceRequest) returns (google.api.HttpBody); rpc UpdateResource(google.api.HttpBody) returns (google.protobuf.Empty); } Example with streaming methods: service CaldavService { rpc GetCalendar(stream google.api.HttpBody) returns (stream google.api.HttpBody); rpc UpdateCalendar(stream google.api.HttpBody) returns (stream google.api.HttpBody); } Use of this type only changes how the request and response bodies are handled, all other features will continue to work unchanged. google.protobuf.Any: type: object properties: type: type: string value: type: string format: binary additionalProperties: true description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. google.protobuf.Timestamp: type: string format: date-time securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: opaque security: - BearerAuth: [] tags: - name: alconost.human.v1.FileService description: |- FileService stores the content tasks attach: upload a file, reference its id from a task's attachments, then download or delete it. - name: alconost.human.v1.TaskService description: |- Pause an automated workflow on work for a human, e.g. to review its output. Create a task, then poll until it reaches a terminal state. Open states: "new" (waiting for an assignee, a price and an estimate), "estimated" (priced; waiting for its creator to accept or decline the price), "queued" (accepted; the assignee hasn't opened it yet), "in_progress" (the assignee has opened it). Terminal states: "done" (the assignee gave the result for the task's type, e.g. a review's verdict), "declined" (the creator turned the price down), "canceled", "expired". A dashboard admin may revert a "done" task to "in_progress", clearing its result, to undo a mistake; callers that already acted on the result are not notified. - name: alconost.human.v1.UserService description: |- Dashboard users: the people who review tasks. Sign-in is invite-only: an admin adds them by email in the dashboard (with a description of what they work on), then they sign in with Google under that email.