> ## Documentation Index > Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a managed service instance > Durable organisation inventory, independent of the confirming actor and review retention. Requires live applications.read and clusters.read on all requested destinations and the service cluster, intersected with live token scopes. Uses primary authority reads so replica lag cannot extend revoked access. Deleted or inaccessible resources are hidden. No credentials, grant IDs, private plans, operation payloads or raw failures are returned. Deployment state reports recorded operation progress only; evidence_updated_at makes its age explicit. Missing, malformed, foreign or later-generation evidence is unknown. Successful deployment remains verification_pending with readiness unverified; this endpoint does not observe a service-specific consumer canary. ## OpenAPI ````yaml https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/instances/{instance_id} openapi: 3.1.0 info: title: Ankra Platform API version: v1 description: >- The Ankra platform HTTP contract. The /api/v1 surface is the public, bearer-authenticated API used by the Ankra CLI, MCP clients and automation; send a personal or service API token as `Authorization: Bearer `. Browser routes under /org and /chat are served on api.platform.ankra.app (each declares that server); they and /oauth/access authenticate with the ankra_session cookie, and mutations also require the X-Ankra-CSRF header. Every operation declares the credential it accepts, and no operation is served without one. This document is published deliberately: it describes the contract only and carries no organisation data or credentials. Report security issues to security@ankra.ai (see /.well-known/security.txt). servers: - url: https://platform.ankra.app security: - BearerAuth: [] tags: - name: Onboarding description: >- Generate a first website from a prompt and deploy it to a new organisation's cluster. - name: Access Gate description: >- Private service sign-in and membership checks for trusted Ankra proxy relays. - name: Canvas Datasets description: >- Read the fixed, named datasets canvas dashboards bind their charts, tables and stats to. - name: Canvases description: >- Keep dashboards and pages in the organisation's canvas library, with revision history, undo and pins. - name: Canvas Pages description: >- Publish a chat canvas artifact at a public pages address and take it down again. - name: Cloud Delegation description: >- Platform browser consent and organisation-bound connections for Ankra Cloud. - name: Organisation IAM description: >- Custom organisation roles and scoped role assignments for member and service-account identities. - name: Clusters description: Create, inspect and manage clusters, and the stacks deployed on them. - name: Managed Clusters description: Provider-managed control planes, driven through one common surface. - name: Imported Clusters description: Clusters that already existed and were connected to Ankra. - name: Cluster Access description: Kubeconfigs, service-account tokens and per-cluster access grants. - name: Kubernetes description: Read and act on the Kubernetes objects inside a cluster. - name: AWS Clusters description: >- Provision and manage self-managed k3s / kubeadm clusters on AWS EC2 in your own VPC. - name: Ankra Cloud Clusters description: >- Provision and manage self-managed kubeadm / k3s clusters on Ankra Cloud servers: a private network, a NAT router and a bastion per cluster. - name: DigitalOcean Clusters description: Provision and manage DigitalOcean Kubernetes clusters. - name: Hetzner Clusters description: Provision and manage Hetzner Kubernetes clusters. - name: OVH Clusters description: Provision and manage OVH Kubernetes clusters. - name: Scaleway Clusters description: Provision and manage Scaleway Kapsule clusters. - name: UpCloud Clusters description: Provision and manage UpCloud Kubernetes clusters. - name: Applications description: Deploy, configure and observe applications across the fleet. - name: Pipelines description: >- Pipeline definitions, the approval of the authority they declare, and the caches pipelines keep between runs. - name: Workspaces description: >- Personal workspaces on the organisation's CI pool where a repository's heavy commands run, and the repository profiles they are built from. - name: Deploy Targets description: >- Environments, the hosts registered to receive deployments, and the releases deployed to them. - name: Deploy Provenance description: >- Whether an application's deploys verify signed provenance from the organisation's own pipeline, the keys that provenance is signed with, and a dry-run that verifies images without deploying. - name: Backups description: >- Backup vaults, restore points, protection posture and captures for stacks and application deployments; a completed capture is not a verified restore. - name: Stack Profiles description: Reusable stack definitions, their versions and sharing. - name: Services description: >- Versioned service packages and explicit sharing. Runtime admission is separate from publication. - name: Charts description: Browse the chart catalogue behind stacks and addons. - name: Helm description: Helm registries, credentials and the charts they expose. - name: Executions description: Long-running platform executions and their jobs. - name: Operations description: Cancel in-flight cluster operations and their jobs. - name: Chat description: Conversational sessions, plans and confirmable actions. - name: AI Management description: >- Customer agent lifecycle, authenticated identity and organisation automation controls. - name: AI Agent Runs description: Autonomous agent runs and their outcomes. - name: AI Tickets description: The AI ticket board, its sync connections and settings. - name: AI Playbooks description: Reusable playbooks the AI lanes execute. - name: AI Conditions description: Conditions that gate AI autonomy. - name: AI Remediation description: >- The organisation's auto-remediation policy: what the AI lanes may fix by themselves, and who approves the rest. - name: AI Engineering Handoffs description: Work the AI lanes escalate to a human engineer. - name: AI Environment description: The environment and base stacks AI demos deploy into. - name: AI Memory description: >- What the assistant has learned about you: your cross-session memories and learned profile. - name: MCP Servers description: >- Register the MCP servers the organisation's AI agents can call, choose their tools and grant them to roles. - name: Security description: Findings, advisories, SBOMs, compliance and posture. - name: Cost description: Cluster and fleet cost, rate cards and cost settings. - name: Decisions description: >- The decision ledger behind the Security and Cost queues: proposals a surface computed, the approve and set-aside decisions people took on them, and the receipts of running them. - name: Usage description: >- What your organisation used of Ankra - vCPU-hours, playgrounds, managed services, hosted logs and metrics, and AI - per meter and period, with how completely it was measured and whether a published rate applies. - name: Billing description: Subscription and spend caps. - name: Organisation description: Members, invitations, audit logs and organisation settings. - name: Account description: >- Your own account: the contact email Ankra mails when it differs from your sign-in address. - name: Account Tokens description: Personal access tokens for the API and CLI. - name: Credentials description: The shared credential store. - name: AWS Credentials description: >- AWS credentials: access keys or CloudFormation-onboarded STS roles for cost, EKS and self-managed provisioning. - name: Ankra Cloud Credentials description: >- Ankra Cloud API tokens, shared by the self-managed and managed Ankra Cloud lanes. - name: Azure Credentials description: Azure credentials and SSH keys. - name: DigitalOcean Credentials description: DigitalOcean credentials and SSH keys. - name: Hetzner Credentials description: Hetzner credentials and SSH keys. - name: HPE Morpheus Credentials description: HPE Morpheus credentials and the capacity and quotas behind them. - name: OVH Credentials description: OVH credentials and SSH keys. - name: Proxmox Credentials description: Proxmox VE credentials and the capacity and quotas behind them. - name: Scaleway Credentials description: Scaleway credentials. - name: UpCloud Credentials description: UpCloud credentials and SSH keys. - name: Data Source Credentials description: Credentials for metrics and log sources. - name: DNS Credentials description: Credentials for DNS providers. - name: Object Storage Buckets description: >- Buckets Ankra creates and manages on an organisation's own provider credentials. - name: DNS description: DNS zones and records, including custom organisation zones. - name: Cloudflare description: Cloudflare domains and the credentials behind them. - name: Avura description: >- The linked Avura organization, the domains it shares with Ankra Platform, and their DNS records. - name: Variables description: Organisation- and cluster-scoped variables. - name: Secret Slots description: >- Store secrets in Vault and reference them by ${SECRET_SLOT:} sentinel instead of by value. - name: SOPS description: Encrypt and decrypt values with the organisation SOPS config. - name: Alerts description: Alert integrations and ingest credentials. - name: Notifications description: Notification routes and their delivery targets. - name: Support description: Support tickets. - name: AI Settings description: Organisation AI provider, model catalog and per-function model settings paths: /api/v1/org/service-admission/instances/{instance_id}: get: tags: - Services summary: Get a managed service instance description: >- Durable organisation inventory, independent of the confirming actor and review retention. Requires live applications.read and clusters.read on all requested destinations and the service cluster, intersected with live token scopes. Uses primary authority reads so replica lag cannot extend revoked access. Deleted or inaccessible resources are hidden. No credentials, grant IDs, private plans, operation payloads or raw failures are returned. Deployment state reports recorded operation progress only; evidence_updated_at makes its age explicit. Missing, malformed, foreign or later-generation evidence is unknown. Successful deployment remains verification_pending with readiness unverified; this endpoint does not observe a service-specific consumer canary. operationId: getServiceInstanceToken parameters: - name: instance_id in: path required: true schema: type: string format: uuid responses: '200': description: >- Authorised durable installation metadata and scoped deployment evidence. content: application/json: schema: $ref: '#/components/schemas/ServiceInstance' '400': description: Bearer token not provided or invalid authorization header '401': description: Authentication required '403': description: Insufficient permission or missing browser CSRF '404': description: Not accessible, absent, or rollout disabled '409': description: Stale revision, missing policy or unavailable deployment binding '422': description: Invalid or ambiguous request '500': description: Internal error '503': description: Rollout availability could not be verified security: - BearerAuth: [] components: schemas: ServiceInstance: type: object additionalProperties: false required: - id - package_version_id - cluster_id - admission_operation_id - name - region - data_boundary - generation - mode - requested_destinations - consumers - cluster_name - cluster_deleted - state - deployment_operation_id - deployment_state - readiness - readiness_check - created_at - released_at - evidence_updated_at - connection - health - retirement properties: id: type: string format: uuid package_version_id: type: string format: uuid cluster_id: type: string format: uuid cluster_name: type: string description: >- The service cluster's name as it reads now, for display; cluster_id is the identity. cluster_deleted: type: boolean description: >- The platform recorded the service cluster deleted, which removed the service with it. The instance stays listed so it can be retired, which only releases its name; its state reads unknown, its readiness stale, and health and connection are null. state: type: string enum: - deploying - deployed - serving - degraded - failed - retiring - released - unknown description: >- The instance's lifecycle in one word, folded at read time from deployment_state, health, readiness and retirement; those fields stay the evidence. released: the instance was released and its name is free. retiring: a confirmed retirement is removing it. failed: its admission or deployment operation failed. deploying: it is being installed, or its workload is rolling out. serving: the platform last observed its workload serving and no readiness check found it failing. degraded: an observation or readiness check found it not serving, or a namespace quota refuses its pods. deployed: its deployment finished and nothing observes its health (a package that is not a first-party engine, or one the health loop has not reached); not a statement that it serves. unknown: the recorded evidence establishes none of these. Precedence is released, retiring, failed, deploying, then the health-based states. admission_operation_id: type: string format: uuid name: type: string region: description: >- Physical cloud region of the placement, for example eu-north-1. It locates infrastructure; it is not the data-location promise, which is data_boundary. type: string data_boundary: description: >- Boundary the data is permitted to stay within, for example eu. Sharing a service across clusters is decided by this boundary, never by the physical region. type: string generation: type: integer format: int64 minimum: 1 mode: type: string enum: - customer - existing - hosted requested_destinations: type: array items: $ref: '#/components/schemas/ServiceReviewDestination' description: >- Requested destinations from the durable plan; not proof of a live service connection. consumers: type: array items: type: object additionalProperties: false required: - id - application_id - cluster_id - namespace - application_name - cluster_name - environment properties: id: type: string format: uuid application_id: type: string format: uuid cluster_id: type: string format: uuid namespace: type: string application_name: type: string nullable: true description: >- The application's name, for display; null when its record carries none. cluster_name: type: string description: The consumer cluster's name, for display. environment: type: object nullable: true additionalProperties: false required: - id - name - role description: >- The application environment the deployment in this namespace belongs to. Null when the application is not deployed to the namespace yet (a planned binding) or its deployment there is not assigned to an environment. properties: id: type: string format: uuid name: type: string role: type: string enum: - playground - production - staging - development - custom connection_delivery: type: object additionalProperties: false required: - state - secret_name - variables - reason description: >- How this consumer receives the service's connection: a Secret Ankra writes into its namespace inside the cluster and the environment variables it carries; values are never returned. Present on the instance detail read only, absent from lists. properties: state: type: string enum: - delivered - pending - unsupported - unknown description: >- delivered: the Secret is observed in the namespace. pending: not yet; the service is still deploying or the application has not deployed since. unsupported: Ankra does not deliver this connection (another cluster, or not an engine Ankra runs in your cluster). unknown: it could not be read. secret_name: type: string description: >- The connection Secret in the consumer's namespace; empty when unsupported or unknown. variables: type: array items: type: string description: >- Environment variable names the application receives: the conventional names when this service holds its protocol's in the environment, then the service's own prefixed names. reason: type: string description: >- Why the state is not delivered, in words a person acts on; empty when delivered. holder_gone: type: object additionalProperties: false required: - protocol - variables - previous_service - services - reason description: >- Present when the service that gave this consumer the protocol's conventional names (DATABASE_URL, ...) no longer serves it while this service and possibly others of the protocol do: the application's deploys are refused until a person chooses which service provides them, or none (PUT .../connection-defaults). Absent otherwise. properties: protocol: type: string variables: type: array items: type: string description: The conventional names withheld. previous_service: type: string description: The service that provided them. services: type: array items: type: string description: The services of the protocol the consumer may choose. reason: type: string description: >- What happened and how to choose, in words a person acts on. description: >- The reviewed plan's consumers with their ids: exactly the set a retirement request names in disconnect_consumer_ids. Reviewed intent, not proof of a live connection. deployment_operation_id: type: string format: uuid nullable: true description: >- Present only when current execution evidence matches the stored receipt and organisation/cluster scope. deployment_state: type: string enum: - accepted - admission_failed - deploying - deployment_failed - verification_pending - unknown - released readiness: type: string enum: - unverified - verifying - ready - degraded - stale description: >- Whether a consumer can use the service, from a scoped consumer-path canary every five minutes: a pod in the instance namespace using the generated credentials by Secret reference the way a consumer would - for PostgreSQL logging in and running SELECT 1, for Valkey, NATS, OpenSearch, the S3 store, VictoriaLogs and VictoriaMetrics writing, reading and deleting a probe-owned record; a result stands fifteen minutes. unverified: no canary covers this instance (a package that is not a first-party engine, a hosted, released or later-generation instance, one with no deployment receipt, or an engine other than PostgreSQL on a cluster whose agent cannot run the canary yet, which readiness_check.reason names); a successful deployment is not readiness. verifying: covered, and no canary has established readiness yet - none has run, or the service is still deploying or inside its first start's grace window. ready: an unexpired canary passed. degraded: an unexpired canary ran and failed after the service had its chance to start. stale: readiness cannot currently be established - the canary could not run (no agent, the cluster unavailable, the canary pod refused or not finishing) or its last result expired; an expired ready is never reported. readiness_check: type: object nullable: true description: >- The canary evidence behind readiness, folded against the database clock at read time. Null when no canary has run at this generation. A canary that could not run leaves an unexpired pass or failure standing until it expires, so observed_at is when the standing result was observed, not necessarily the latest attempt. When readiness is unverified because the cluster's agent cannot run the engine's canary, observed_at, expires_at and last_passed_at are null and reason names the agent upgrade. Never carries a probe log or a credential. additionalProperties: false required: - observed_at - expires_at - reason - last_passed_at properties: observed_at: type: string format: date-time nullable: true description: >- When the standing result was observed; null when the cluster's agent cannot run the canary. expires_at: type: string format: date-time nullable: true description: >- When the standing result stops counting; null when the cluster's agent cannot run the canary. reason: type: string description: One line naming what decided the readiness. last_passed_at: type: string format: date-time nullable: true description: >- When a canary last passed at this generation; null when none has. It survives expiry. created_at: type: string format: date-time released_at: type: string format: date-time nullable: true evidence_updated_at: type: string format: date-time nullable: true connection: type: object nullable: true description: >- Where a first-party engine instance is reached inside its cluster and which Secret in its namespace holds the credentials the engine generated. Derived from the engine profile, not observed; null for any other package, and for a released instance, whose retirement deleted the namespace and the Secret. additionalProperties: false required: - namespace - endpoints - secret properties: namespace: type: string endpoints: type: array items: type: object additionalProperties: false required: - name - address properties: name: type: string address: type: string secret: type: object additionalProperties: false required: - name - keys properties: name: type: string keys: type: array items: type: string health: type: object nullable: true description: >- Health as the platform last observed it from the service cluster's synced state: whether the engine's workload reports ready, its Service and credentials Secret exist, and the stack that owns it is still deployed. It is not readiness - no consumer connection is proven. Evidence past expires_at reads unknown, folded against the database clock at read time, so a stopped observer never leaves a stale serving. Null when nothing has observed this generation: a package that is not a first-party engine, an instance not deployed yet, a released instance, or one not observed yet. additionalProperties: false required: - state - observed_at - expires_at - reason - quota properties: state: type: string enum: - serving - progressing - degraded - unknown description: >- serving: every check passed on an authoritative view. progressing: a check failed while the deployment is in flight or inside the engine's grace window. degraded: a check failed after the grace window, the deployment failed, or the owning stack is gone or being removed. unknown: something could not be read - the cluster's watch of a resource type is not synced or fresh - or the evidence expired. observed_at: type: string format: date-time expires_at: type: string format: date-time reason: type: string description: >- One line naming what decided the state. While a quota refusal stands and the service is not serving, it leads with the refusal: blocked by namespace quota ( /): . quota: type: object description: >- What the same observation could see of namespace ResourceQuota refusals in the instance namespace and the namespaces of the shared operators the engine needs (cnpg-system for PostgreSQL). Read from the cluster's own events: a ReplicaSet's FailedCreate or a virtual cluster syncer's SyncError naming an exceeded quota, last seen within 30 minutes. refused: such an event stands, carried verbatim in refusal. none_observed: no such event in the namespaces listed, on an events watch that is synced and fresh - it does not cover refusals worded otherwise (a LimitRange bound, an admission webhook). unknown: no such event, and the events watch is not synced and fresh, the evidence expired, or the observation recorded no quota check. A refusal does not decide state; a serving instance can carry one it has outlived. additionalProperties: false required: - state - namespaces - refusal properties: state: type: string enum: - refused - none_observed - unknown namespaces: type: array items: type: string description: >- The namespaces read; none_observed speaks for these only. Empty when the observation recorded no quota check. refusal: type: object nullable: true description: The freshest refusal, present exactly when state is refused. additionalProperties: false required: - namespace - object_kind - object_name - message - last_seen_at properties: namespace: type: string object_kind: type: string description: >- Kind of the object the event is about: the ReplicaSet or Job that could not create a pod, or the virtual pod the syncer could not place. Empty when the event names none. object_name: type: string message: type: string description: The event's message verbatim, up to 480 characters. last_seen_at: type: string format: date-time retirement: allOf: - $ref: '#/components/schemas/ServiceInstanceRetirement' nullable: true description: >- The latest confirmed retirement, running or settled; null when none was ever confirmed. A settled outcome other than retired left the service and its name in place. ServiceReviewDestination: type: object additionalProperties: false required: - application_id - cluster_id - namespace properties: application_id: type: string format: uuid cluster_id: type: string format: uuid namespace: type: string ServiceInstanceRetirement: type: object additionalProperties: false description: >- The latest confirmed retirement of an instance: recorded progress, not an observation of the cluster. required: - id - state - phase - execution_id - requested_at - settled_at - outcome - reason - data_disposal - kept_data properties: id: type: string format: uuid state: type: string enum: - in_progress - settled phase: type: string enum: - retire_stack - await_teardown - dispose_data nullable: true description: The phase the retirement is in, or was in when it settled. execution_id: type: string format: uuid requested_at: type: string format: date-time settled_at: type: string format: date-time nullable: true outcome: type: string enum: - retired - removal_failed - disposal_unknown - refused - interrupted nullable: true description: >- Only retired releases the service's name; every other outcome left the service and its name in place. Whether a retired service's data may remain is data_disposal, beside it. reason: type: string nullable: true data_disposal: type: string enum: - complete - data_kept - unconfirmed nullable: true description: >- What became of the service's data once the retirement settled retired. complete only when Ankra can show the data is gone: nothing was ever deployed, or every claim of the deleted namespace was listed and every volume behind them was read gone. data_kept: a persistent volume was observed still holding the data after the namespace was gone. unconfirmed: every uncertain case - a volume could not be read or named another claim, a Retain volume's object was gone (its disk may remain), a claim had no volume when reviewed, the review was incomplete, the volumes were never read or their record is damaged, the service had no namespace of its own, or its cluster was recorded deleted in Ankra (which does not show its storage was destroyed). Null for every other outcome and until the retirement settles. data_kept and unconfirmed carry kept_data. kept_data: allOf: - $ref: '#/components/schemas/ServiceRetirementKeptData' nullable: true description: >- What a retirement that released the name left of the service's data, or could not rule out, with the next step. Null unless data_disposal is data_kept or unconfirmed. ServiceRetirementKeptData: type: object additionalProperties: false description: >- The service's data a retirement that released the name left behind or could not confirm gone: which persistent volumes, on which cluster, and the Ankra CLI commands to inspect and erase them. Deleting the namespace released the volumes; their reclaim policy decides the data, and Ankra does not delete a retained volume itself. required: - cluster_id - namespace - observed_at - retained_volumes - unconfirmed_volumes - unbound_claims - complete - next_step - commands properties: cluster_id: type: string format: uuid nullable: true description: >- The service's cluster. Null when its record could not be read; then commands is empty. namespace: type: string nullable: true description: >- The deleted namespace the volumes' claims lived in; null when the service had no namespace of its own. observed_at: type: string format: date-time nullable: true description: >- When Ankra last read the volumes, once, after the namespace was gone. Never re-checked: a volume named here may have been removed since. Null when the volumes were never read. retained_volumes: type: array items: type: string description: >- Persistent volumes observed still holding the service's data when Ankra last looked (observed_at). unconfirmed_volumes: type: array items: type: string description: >- Reviewed volumes Ankra cannot confirm are gone: it could not read them, or they named another claim by the time it looked. Offered for inspection only, never for erasing. unbound_claims: type: array items: type: string description: >- Volume claims that had no volume when the retirement was reviewed; one may have bound a volume before the namespace was deleted, which nobody read. complete: type: boolean description: >- Every volume claim in the namespace was listed at review and every volume behind them was read. False means a volume not named here may still hold the data. next_step: type: string description: What to do, in words. commands: type: array items: type: object additionalProperties: false required: - purpose - volume - command properties: purpose: type: string enum: - inspect - erase - find description: >- inspect shows one volume; erase is a JSON patch that first tests the volume still names the service's claim (namespace, and the reviewed claim's name and uid when known) and then sets its reclaim policy to Delete, so its provisioner deletes the volume and the disk behind it, which cannot be undone; it is offered only for a volume observed retained for the service's claims; find lists the cluster's persistent volumes to find one Ankra could not name. volume: type: string nullable: true command: type: string description: The Ankra CLI command. securitySchemes: BearerAuth: bearerFormat: PAT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.