{"openapi":"3.1.0","info":{"title":"voar","version":"0.1.0","description":"Create an organization API key in your organization's Settings at https://app.voar.dev and send it with every call. Read the guide at https://voar.dev/docs#api."},"servers":[{"url":"https://api.voar.dev/v1"}],"tags":[{"name":"Account","description":"Organization summary, credit balance, and concurrency."},{"name":"Jobs","description":"Recent GitHub Actions jobs for the bound organization."},{"name":"Usage","description":"Monthly finished jobs, billed units, and paid cost."}],"paths":{"/account":{"get":{"operationId":"get_account","tags":["Account"],"summary":"Read organization summary","description":"Read the bound organization's plan, credit balance, free units per month and how many are used, concurrency limit, live runners, and queued jobs.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Read organization summary","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"login":{"type":"string","description":"GitHub organization login."},"avatarUrl":{"description":"GitHub avatar URL for the organization.","type":["string","null"]},"role":{"type":"string","enum":["owner","admin","member"],"description":"Role of the member who created the API key in this organization."},"status":{"type":"string","enum":["active","suspended","uninstalled"],"description":"Installation status: active, suspended, or uninstalled."},"currency":{"type":"string","enum":["brl","usd","eur"],"description":"Billing currency for the organization: brl, usd, or eur."},"balanceMicros":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Prepaid credit balance in micro-units of currency (1,000,000 = 1.00)."},"plan":{"type":"string","enum":["standard","internal"],"description":"Organization billing plan: standard or internal."},"currencyLocked":{"type":"boolean","description":"True once the first payment fixed the billing currency."},"hasPaid":{"type":"boolean","description":"True once the organization completed at least one credit purchase."},"freeUnitsPerMonth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Monthly free allowance in 2-vCPU minutes."},"freeUnitsUsed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Free units already consumed in the current billing month."},"freeResetsAt":{"type":"string","description":"ISO 8601 timestamp when the monthly free units reset."},"unitPriceMicros":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Price of one paid unit in micro-units of currency."},"concurrencyLimit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Maximum concurrent machines allowed for this organization."},"activeRunners":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Machines currently provisioning, booting, or running."},"queuedJobs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Jobs currently waiting for a machine."},"repositorySelection":{"anyOf":[{"type":"string","enum":["all","selected"]},{"type":"null"}],"description":"Which organization repositories the GitHub App installation covers."},"lowBalanceAlertMicros":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credit balance threshold in micros that triggers a low-balance alert."},"installationSettingsUrl":{"description":"GitHub settings URL for the App installation.","type":["string","null"]}},"required":["login","avatarUrl","role","status","currency","balanceMicros","plan","currencyLocked","hasPaid","freeUnitsPerMonth","freeUnitsUsed","freeResetsAt","unitPriceMicros","concurrencyLimit","activeRunners","queuedJobs","repositorySelection","lowBalanceAlertMicros","installationSettingsUrl"],"additionalProperties":false,"description":"Summary of the GitHub organization bound to the API key."}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-mcp-tool":"get_account","x-scope":"account:read"}},"/jobs":{"get":{"operationId":"list_jobs","tags":["Jobs"],"summary":"List recent jobs","description":"List recent GitHub Actions jobs for the bound organization, newest first, with runner size, status, conclusion, billed units, cost in micros, and any problem that blocked a launch.","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of jobs to return, from 1 to 100.","schema":{"default":50,"description":"Maximum number of jobs to return, from 1 to 100.","type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","required":false,"description":"Return only jobs queued before this ISO 8601 timestamp, for keyset pagination.","schema":{"description":"Return only jobs queued before this ISO 8601 timestamp, for keyset pagination.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"List recent jobs","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"GitHub Actions workflow_job id."},"repo":{"type":"string","description":"Full repository name as owner/name."},"workflow":{"description":"Workflow name reported by GitHub.","type":["string","null"]},"name":{"description":"Job name reported by GitHub.","type":["string","null"]},"label":{"type":"string","description":"runs-on label requested by the workflow job."},"size":{"anyOf":[{"type":"string","enum":["2vcpu","4vcpu","8vcpu","16vcpu"]},{"type":"null"}],"description":"Machine size resolved from the label, or null when the label was invalid."},"status":{"type":"string","enum":["queued","in_progress","completed"],"description":"Job lifecycle state: queued, in_progress, or completed."},"conclusion":{"description":"GitHub job conclusion once completed, such as success, failure, or cancelled.","type":["string","null"]},"queuedAt":{"type":"string","description":"ISO 8601 timestamp when GitHub queued the job."},"startedAt":{"description":"ISO 8601 timestamp when the runner started the job, or null while waiting.","type":["string","null"]},"completedAt":{"description":"ISO 8601 timestamp when the job completed, or null while running.","type":["string","null"]},"billedUnits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Units billed for the finished job (whole minutes times the machine rate)."},"costMicros":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Paid cost in micro-units of currency after any free units."},"htmlUrl":{"description":"GitHub web URL for the workflow job.","type":["string","null"]},"problem":{"anyOf":[{"type":"string","enum":["unknown-size","unknown-image","extra-label","two-voar-labels","no-credit","launch-failed","account-inactive"]},{"type":"null"}],"description":"Reason the job did not receive a machine, or null when it ran normally."}},"required":["id","repo","workflow","name","label","size","status","conclusion","queuedAt","startedAt","completedAt","billedUnits","costMicros","htmlUrl","problem"],"additionalProperties":false,"description":"One GitHub Actions job seen by voar."},"description":"Jobs matching the query, newest first."}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-mcp-tool":"list_jobs","x-scope":"jobs:read"}},"/usage":{"get":{"operationId":"get_usage","tags":["Usage"],"summary":"Read monthly usage","description":"Read the bound organization's finished jobs, billed units, and paid cost in micros for a billing month (America/Sao_Paulo), broken down by day. Costs are in the currency that get_account returns.","parameters":[{"name":"month","in":"query","required":false,"description":"Billing month as YYYY-MM in America/Sao_Paulo. Defaults to the current month.","schema":{"description":"Billing month as YYYY-MM in America/Sao_Paulo. Defaults to the current month.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Read monthly usage","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"month":{"type":"string","description":"Billing month as YYYY-MM in America/Sao_Paulo."},"days":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","description":"Calendar day as YYYY-MM-DD in America/Sao_Paulo."},"jobs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Finished jobs on this day."},"units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total units consumed by finished jobs on this day."},"costMicros":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Paid cost in micro-units of currency on this day."}},"required":["day","jobs","units","costMicros"],"additionalProperties":false,"description":"Finished jobs, units, and paid cost for one day."},"description":"Daily totals for every day in the billing month that had finished jobs."},"totals":{"type":"object","properties":{"jobs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Finished jobs in the billing month."},"units":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total units consumed by finished jobs in the billing month."},"costMicros":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total paid cost in micro-units of currency in the billing month."}},"required":["jobs","units","costMicros"],"additionalProperties":false,"description":"Month totals across all days."}},"required":["month","days","totals"],"additionalProperties":false,"description":"Monthly usage breakdown for the bound organization."}}}}}},"default":{"description":"Any other failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-mcp-tool":"get_usage","x-scope":"usage:read"}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_ERROR","BAD_SIGNATURE","UNAUTHORIZED","INVALID_TOKEN","FORBIDDEN","NOT_FOUND","CONFLICT","PAYMENT_REQUIRED","RATE_LIMIT_EXCEEDED","INTERNAL_ERROR","SERVICE_UNAVAILABLE"],"description":"What went wrong, as a word a program can check."},"message":{"type":"string","description":"What went wrong, as a sentence."},"messageKey":{"type":"string","description":"`message` as a key, to show it in your reader's language, with `params` filling its blanks."},"params":{"type":"object","additionalProperties":{"type":["string","number"]},"description":"The values that fill `messageKey`'s blanks, such as a limit."},"details":{"description":"More about this error, such as retryAfterSecs."}}}}}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Send your organization API key as \"Authorization: Bearer voar_...\"."}}},"x-mcp-tools":[{"name":"get_account","title":"Read organization summary","description":"Read the bound organization's plan, credit balance, free units per month and how many are used, concurrency limit, live runners, and queued jobs.","inputSchema":{"type":"object","properties":{},"additionalProperties":false}},{"name":"list_jobs","title":"List recent jobs","description":"List recent GitHub Actions jobs for the bound organization, newest first, with runner size, status, conclusion, billed units, cost in micros, and any problem that blocked a launch.","inputSchema":{"type":"object","properties":{"limit":{"default":50,"description":"Maximum number of jobs to return, from 1 to 100.","type":"integer","minimum":1,"maximum":100},"before":{"description":"Return only jobs queued before this ISO 8601 timestamp, for keyset pagination.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"additionalProperties":false}},{"name":"get_usage","title":"Read monthly usage","description":"Read the bound organization's finished jobs, billed units, and paid cost in micros for a billing month (America/Sao_Paulo), broken down by day. Costs are in the currency that get_account returns.","inputSchema":{"type":"object","properties":{"month":{"description":"Billing month as YYYY-MM in America/Sao_Paulo. Defaults to the current month.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},"additionalProperties":false}}]}