Skip to content

Document API v1/v2 availability on CircleCI Server (SUPENG-552) - #10678

Open
denislemire wants to merge 1 commit into
mainfrom
docs/supeng-552-api-availability-server
Open

denislemire wants to merge 1 commit into
mainfrom
docs/supeng-552-api-availability-server

Conversation

@denislemire

Copy link
Copy Markdown
Contributor

Summary

  • Adds a Guides page that compares API v1.1 and v2 availability on CircleCI Server 4.7, 4.8, 4.9, and 4.10 with Cloud.
  • Replaces the hostname-only Server API note so readers are not told that swapping circleci.com is enough.
  • Links the page from the API intro, developers guide, API homepage, and Server 4.7–4.10 FAQs.

The Cloud OpenAPI reference remains the schema source. This page covers Cloud-only paths, version gates, working endpoint families, and Server admin v1. It does not enumerate every OpenAPI operationId.

Test plan

  • Vale: confirm ci/circleci: lint is green on the new and changed .adoc files
  • Preview the build artifact and check table scroll on the new page
  • Follow xrefs from API intro, developers guide, API homepage, and a Server FAQ
  • On-prem review of the 4.7 vs 4.8+ status columns (project create, settings, usage export, pipeline definitions)

The Cloud API reference implies hostname substitution is enough. Add a
Server matrix for Cloud-only, version-gated, and admin endpoints (SUPENG-552).

Co-authored-by: Cursor <cursoragent@cursor.com>
@linear-code

linear-code Bot commented Aug 25, 2026

Copy link
Copy Markdown

SUPENG-552

@rosieyohannan

Copy link
Copy Markdown
Contributor

This looks like a great idea. I would love to get the server version support "tags" or something into the API reference docs too. Could use this list as a reference to do that if it's fully verified

Copy link
Copy Markdown
Contributor Author

This was verified from code as source of truth so it should be pretty accurate.

I actually meant to talk to you about this PR to see if you had any thoughts on how to best structure this info… Docs on API availability are a bit lacking, this PR was triggered by a ticket from one of our Server customers.

Also looking to strike the right balance of customers being able to find what does / doesn't exist without exposing too much unnecessary information and/or internals… The PR probably still needs a bit more work in that regard.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants