{"id":45187749,"url":"https://github.com/cycleplatform/api-spec","last_synced_at":"2026-02-20T11:04:38.140Z","repository":{"id":166207995,"uuid":"587073458","full_name":"cycleplatform/api-spec","owner":"cycleplatform","description":"OpenAPI spec files for Cycle APIs","archived":false,"fork":false,"pushed_at":"2026-02-19T19:11:40.000Z","size":2412,"stargazers_count":5,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-19T22:05:09.208Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cycleplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-01-09T22:27:23.000Z","updated_at":"2026-02-19T19:11:42.000Z","dependencies_parsed_at":"2023-11-15T20:27:45.521Z","dependency_job_id":"ef38bc7e-2950-4b82-a458-afdfebc2d24e","html_url":"https://github.com/cycleplatform/api-spec","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/cycleplatform/api-spec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Fapi-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Fapi-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Fapi-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Fapi-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cycleplatform","download_url":"https://codeload.github.com/cycleplatform/api-spec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cycleplatform%2Fapi-spec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29648486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T09:27:29.698Z","status":"ssl_error","status_checked_at":"2026-02-20T09:26:12.373Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T11:04:37.312Z","updated_at":"2026-02-20T11:04:38.133Z","avatar_url":"https://github.com/cycleplatform.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cycle API Spec\n\n\u003ca href=\"https://cycle.io\"\u003e\n\u003cpicture class=\"red\"\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://static.cycle.io/icons/logo/logo-white.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://static.cycle.io/icons/logo/cycle-logo-fullcolor.svg\"\u003e\n  \u003cimg alt=\"cycle\" width=\"300px\" src=\"https://static.cycle.io/icons/logo/cycle-logo-fullcolor.svg\"\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\n\nThis repository contains the [OpenAPI](https://www.openapis.org/) definitions for the [Cycle API](https://cycle.io/docs/api/platform). It is used in several downstream API clients and projects, and is the basis of our API documentation.\n\n⚠️ This spec is still under development. While most endpoints should be stable, there are still edge cases and small discrepancies that are actively being worked on. While no major breaking changes are expected, we can't guarantee that any downstream clients won't be affected by changes to schemas.\n\n## APIs\n\n### Platform API\n\nhttps://api.cycle.io\n\n[Documentation](https://cycle.io/docs/api/platform)\n\nThe platform API is the general use API for the Cycle Platform, and is available to all Cycle customers. It is the same API consumed by Cycle's portal, and is the main way to interact with all aspects of the platform.\n\nSee the [platform](./platform/) folder for implementation.\n\n### Internal API\n\n[Documentation](https://cycle.io/docs/api/internal)\n\nInside every container running on Cycle, there is a Unix socket mounted at `/var/run/cycle/api/api.sock`. You can send HTTP requests over this socket to access information about the local environment, access secrets, and much more. The way this internal API functions is very similar to how Cycle's main API works, though the purpose is different. The internal API is primarily used by instances to learn about their environment, and dynamically update as deployments change.\n\nSee the [internal](./internal/) folder for implementation.\n\n### Scheduler API\n\n[Documentation](https://cycle.io/docs/api/scheduler)\n\nThe scheduler API is used to interact with the [Scheduler Service](https://cycle.io/docs/platform/scheduler-service) inside of\nan environment on Cycle. The scheduler service can be accessed from other containers in the environment over the private network,\nor the scheduler service can be [made available over the public internet](https://cycle.io/docs/platform/scheduler-service).\n\nSee the [scheduler](./scheduler/) folder for implementation.\n\n### Infrastructure Abstraction Layer API\n\n[Documentation](https://cycle-ial.redoc.ly/)\n\nCycle's Infrastructure Abstract Layer (IAL) API. Endpoints listed here should be implemented by the customer, and Cycle will call the various endpoints over the lifecycle of provisioning and decommissioning servers.\n\nFor more information, check out the official [Infrastructure Abstraction Layer Documentation](https://cycle.io/docs/platform/infrastructure-abstraction-layer).\n\n### Stack Spec\n\nWhile not truly an API spec, the stack spec defines the JSON schema for a [Cycle Stack File](https://cycle.io/docs/platform/introduction-to-stacks). The JSON schema is useful for editor validation etc.\n\nThe compiled stack spec schema is committed to this repo and hosted on [JSON Schema Store](https://www.schemastore.org/json/)\n\n## Building the APIs\n\nThe APIs can be consumed by tools that support stitching together specs divided between multiple files, or built\ninto a single file using the [Redocly CLI](https://redocly.com/redocly-cli/).\n\n### Prerequisites\n\nYou must have `npm` installed on your machine, or run inside a container with `npm` in the PATH.\n\n### Building the Platform API\n\n`npm run build:platform`\n\nThe outputted file is located at `/dist/platform.yml`\n\n### Building the Internal API\n\n`npm run build:internal`\n\nThe outputted file is located at `/dist/internal.yml`\n\n### Building the Scheduler API\n\n`npm run build:scheduler`\n\nThe outputted file is located at `/dist/scheduler.yml`\n\n### Building the Infrastructure Abstraction Layer API\n\n`npm run build:ial`\n\nThe outputted file is located at `/dist/ial.yml`\n\n### Building the Stack Spec\n\n`npm run build:stackspec`\n\nThis will build the stack spec into a single JSON schema file, and save it to ./stackspec/stackspec.json.\n\n**This file should be committed to the repo.**\n\n## Downconverting to OpenAPI 3.0.3\n\nThe API specs in this repo are written using the OpenAPI 3.1.0 standard. Some code generators and other tools haven't yet\nbeen updated to support 3.1.0, which can be an inconvenience. For us, it seems nearly all golang client generators don't\nsupport 3.1.0 (if you find one let us know!).\n\nTo resolve this, we've created a script that will downconvert the openapi spec to 3.0.3. Of course, some fidelity is lost\nwith these conversions, so it may not be a perfect 1:1 with the 'true' spec, but hopefully is good enough to generate clients\noff of when necessary.\n\nTo downconvert, run `npm run downconvert:platform`. The script will output to `dist/platform-3.0.3.yml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcycleplatform%2Fapi-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcycleplatform%2Fapi-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcycleplatform%2Fapi-spec/lists"}