APIX Services Profile: Discovery Infrastructure for Web API and Bot Services

Introduction The APIX Core Infrastructure defines the common foundation for agent-oriented service discovery: the governance model, trust model dimensions, commercial onboarding, sanctions compliance, and the base Index API. That document is the authoritative reference for all concepts and normative requirements shared across service types. This document extends APIX Core for web API and bot-consumable services: services that expose a stable HTTPS endpoint, publish a machine-readable specification document, and are verifiable by an automated crawler. These are the primary service type for which APIX was originally conceived. The defining characteristics of an API service, as distinct from an IoT device service, are:

A stable, publicly accessible entry_point URL.
A machine-readable specification at a public spec.url (OpenAPI, MCP, AsyncAPI, or GraphQL SDL).
Liveness maintained by Spider health checks, not device presence signals.
No instance layer: the service is the service; there is no per-physical-unit record.

Implementors MUST satisfy all normative requirements in before applying the additional requirements in this document. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

Terminology The following terms are defined in and used here without redefinition: APIX, APM, APIX Manifest, service_id, trust model, organisation trust level (O-0 through O-5), service verification level (S-0 through S-4), liveness, commercial contract, sanctions screening. Additional terms defined in this document: API Service — A service registered with spec.type set to a web-protocol value (openapi, mcp, asyncapi, graphql). Has a stable entry_point URL and a machine-readable spec document. Verified by the APIX Spider. APIX Spider — The automated crawler component that verifies API service registrations by fetching health endpoints and specification documents, comparing them against registered snapshots, and updating service verification levels. Registered Spec Snapshot — The machine-readable specification document fetched and stored by the Spider at first registration, or at each APM update that increments api_version. The snapshot is the reference for structural consistency checks on subsequent Spider runs. Liveness Monitoring Configuration — The per-service setting that determines how frequently the Spider rechecks a service's health endpoint and specification document. Liveness — Defined in Section 2. For API services, liveness is measured by the APIX Spider via periodic HTTPS health checks against {entry_point}/health. The Spider records response availability, response time, and uptime percentage. Device service liveness uses a different mechanism (see ). Service Record — The APIX-maintained record for an API service, combining the APM submitted by the Service Owner with Spider-verified trust metadata. Available at two granularity levels: Level 1 (summary, returned in search results) and Level 2 (full record, returned on detail fetch). Lifecycle Stage — The current development and support status of a service: experimental, beta, stable, deprecated, or sunset. spec_consistency — A Spider-maintained field with three values: consistent (spec matches snapshot), mismatch (spec changed without APM version update), unreachable (spec URL not fetchable or parseable). Accredited Verifier — An organisation accredited by the governing body to perform O-4 and O-5 organisation trust assessments.

APM for API Services

Required Fields The APIX Manifest for an API service extends the base APM format defined in . The following complete schema applies to all services with spec.type in the Protocol Type Registry (Section 4): Field notes: last_verified_against_target is OPTIONAL and self-reported: it records the freshness of this service's content against the external target it describes (primarily for meta/description services, capability meta.api-spec). The index validates the timestamp format only, not its truthfulness. owner.contacts.operations MUST be provided. It is the primary notification address for all automated Spider alerts: spec fetch failures at Cluster 2 entry, liveness degradation, and recovery confirmations. This address SHOULD reach the team responsible for keeping the service registration current. owner.contacts.escalation is OPTIONAL but RECOMMENDED. It is the escalation address sent to when failures reach Cluster 3 — indicating a persistent problem that has not been resolved through the Cluster 1 and Cluster 2 retry windows and likely requires management attention or a deliberate APM configuration update. This address SHOULD reach a team lead, service owner, or on-call manager. It MUST NOT be identical to operations — if the same person handles both, the escalation path provides no additional coverage. api_version MUST follow Semantic Versioning 2.0.0. It describes the version of the service's own API, not the APM format version. Each api_version value is bound to exactly one registered spec snapshot and carries an immutable field structure definition. The schema associated with a published api_version MUST NOT change after first publication:

Adding a field requires a new minor version (e.g., 2.3.0 → 2.4.0).
Removing a field, changing a field type, or making any other breaking change requires a new major version (e.g., 2.4.0 → 3.0.0).

This is not a convention — it is a hard invariant enforced by the snapshot model. A consuming agent that targets v2.4 receives a permanent contract: every service matching that version will expose exactly the fields defined for v2.4, no more and no less, for the lifetime of that registration. Service Owners are therefore free to drop outdated fields at a major version boundary without deprecation gymnastics — the major bump is the explicit, sufficient notice to consumers. A Service Owner who modifies the live spec document at spec.url without submitting an APM update with a new api_version value WILL produce a structural mismatch between the live document and the stored snapshot. The Spider MUST record this as an S-2 consistency failure and MUST surface it in the Service Record as a standard_warnings entry. Operators who need to change their API MUST register a new api_version. This protects consuming agents from silent contract breakage. language is OPTIONAL. When present, it MUST be a non-empty JSON array of BCP 47 language tags (). It declares the natural languages in which the service's API responses, documentation, and user-facing content are available. If omitted, the default value is ["en"]. Agents MAY use this field to select services that operate in a required language. Example: ["de", "en"] for a service supporting German and English. authentication is OPTIONAL but RECOMMENDED. When present, it MUST contain a methods array listing one or more of the following values: "oauth2", "api_key", "bearer", "mtls", "none". A service that requires no authentication MUST declare ["none"] explicitly. When "oauth2" is in methods, oauth2_discovery_url MUST be provided; it MUST point to a valid OAuth2 discovery document (RFC 8414 or OpenID Connect Discovery). The authentication field enables agents to pre-qualify whether they can authenticate with a service before invocation, avoiding wasted round-trips and quota consumption against services the agent cannot use. The APIX Spider does not verify credential validity; it verifies only that oauth2_discovery_url, when declared, is reachable and returns a parseable discovery document. pricing is OPTIONAL. When present, it MUST contain a model field with one of the following values:

"free" — no charge for any usage; pricing_url MAY be omitted.
"freemium" — a free tier exists; pricing_url SHOULD be provided.
"paid" — all usage is charged; pricing_url MUST be provided.
"enterprise" — pricing is individually negotiated; pricing_url MUST be provided.
"dynamic" — price varies based on service load or other real-time factors; pricing_endpoint MUST be provided.

pricing.model is self-declared and is not verified by the APIX Spider. The index stores and exposes only the declared model value and the pricing_endpoint URL; it does not fetch, cache, or display current prices. Consuming agents are solely responsible for querying the pricing_endpoint directly before invocation and for evaluating the returned price against their operator-configured budget constraints. Misrepresentation of the pricing model (e.g., declaring "free" while charging) constitutes a breach of the service owner's registration contract and MUST result in suspension at O-3+. pricing.pricing_url MUST be a stable HTTPS URL pointing to a human-readable pricing page. Agents MAY follow this URL for full pricing detail. pricing.pricing_endpoint is REQUIRED when model is "dynamic" and MUST NOT be present for any other model value. It is a stable HTTPS URL that agents query immediately before service invocation to obtain the current price. The endpoint MUST respond with: quote_id is a single-use price reservation token issued by the service for this specific price quote. It MUST be treated as a binding commitment: the service MUST honour the quoted price_per_unit when the agent presents a valid, non-expired quote_id at invocation time. The quote_id expires at valid_until and MUST NOT be accepted after that timestamp. A quote_id is single-use — once presented in an invocation it is consumed and MUST NOT be accepted again. How the agent presents the quote_id during invocation (HTTP header, request body field, or other mechanism) is defined by the service's own API documentation; APIX does not specify the invocation protocol. An agent MUST NOT invoke the service after valid_until without re-querying the pricing endpoint to obtain a fresh quote_id. An agent MAY compare price_per_unit against its operator-configured budget ceiling and MUST abandon the invocation and discard the quote_id if the ceiling is exceeded. load_factor is OPTIONAL and indicates the current multiplier relative to the service's baseline price (1.0 = baseline). lifecycle_stage defines the publication maturity of this API service. API service lifecycle is defined by this profile. Valid values are experimental, beta, stable, deprecated, and sunset. Default if omitted is stable. Services at experimental or beta are excluded from default search results (see Section 7.2).

Stage	Meaning
`experimental`	Pre-release. Interface may change without notice.
`beta`	Feature-complete but not yet declared stable. Breaking changes possible.
`stable`	Production-ready. Breaking changes require a new `api_version`.
`deprecated`	Service owner is winding down. Successor SHOULD be declared via `supersedes`.
`sunset`	Service endpoint will go dark at the declared `sunset_date`. Agents MUST stop using the service by that date.

Transitions are unidirectional: experimental → beta → stable → deprecated → sunset. supersedes is OPTIONAL. When set, the index MUST automatically set superseded_by on the referenced entry. The referencing service MUST be registered under the same organisation account. trust fields are set exclusively by the index operator based on verification outcomes. APM submissions that include trust field values MUST have those values overwritten by the index upon processing. standard_warnings is set exclusively by the index operator. It is populated only after the grace period for the relevant deprecation has elapsed (see Section 4.3). During the grace period the field MUST be empty even if the service uses a deprecated value. Service Owners MUST NOT submit this field; submitted values MUST be ignored. custom is OPTIONAL. When present, it MUST be a JSON array of strings. Each string MUST use reverse-domain notation (e.g., "com.example.coverage_polygon") to prevent key collisions between independent adopters. The array MUST NOT contain more than 20 entries. Each entry MUST NOT exceed 128 characters. The custom array is a capability declaration list — it signals that the service exposes properties not yet covered by the standard schema, without encoding their values in the index. Values associated with declared custom properties are defined and published by the registrant outside the index (e.g., in their API documentation or spec document) and are retrieved directly from the service. The index stores and exposes only the declared key names. The custom field is the governed extension mechanism for early adoption of field patterns that may be standardised in a future APM version. The APIX Spider records declared key names in the index's custom key registry. Consuming agents can discover services that declare a known custom property via the custom_key search parameter; interpretation of a custom property's semantics requires out-of-band agreement between registrant and consumer. The promotion path: when a custom key appears in APM submissions from five (5) or more independent organisations, The governing body MAY open a governance track to evaluate the pattern as a candidate standard field in a future APM version. Registrants are encouraged to document custom property semantics publicly to support interoperability and accelerate standardisation. notifications is OPTIONAL for experimental and beta lifecycle stages and RECOMMENDED for stable. If notifications.supported is true, notifications.channels MUST contain at least one entry. entry_point is the base HTTPS URL of the service, used by consuming agents to construct API calls. The following normative requirements apply:

entry_point MUST use the https scheme. HTTP entry points MUST be rejected at registration.
entry_point MUST remain stable for the lifetime of the service registration. A change to entry_point MUST be submitted as an APM update and MUST trigger immediate Spider re-verification.
The Spider MUST NOT hit entry_point directly for liveness checks. Instead, the Spider checks entry_point + /health (see Section 5.2).
HTTP redirects from entry_point are permitted for consuming agents but MUST NOT be present at entry_point/health (the health endpoint MUST respond directly without redirect).

entry_point/health is the mandatory liveness endpoint. Every registered service MUST expose a health endpoint at the path /health relative to entry_point. This endpoint:

MUST return HTTP 2xx when the service is operational.
MUST return without requiring authentication.
MUST respond within a reasonable timeout (RECOMMENDED: 5 seconds).
SHOULD return a JSON body of the form {"status": "ok", "api_version": "<semver>"}. If api_version is present, the Spider SHOULD cross-check it against the APM api_version field; a mismatch MUST be recorded as a warning in the Service Record.
MUST NOT be used by consuming agents for API calls — it is a Spider-facing infrastructure endpoint only.

spec.url is the URL to the machine-readable API specification document (OpenAPI JSON/YAML, MCP manifest, AsyncAPI document, or GraphQL SDL).

spec.url MUST use the https scheme.
spec.url MUST be publicly accessible without authentication. A spec behind authentication cannot be fetched by the Spider and permanently prevents the service from reaching S-2.
On the initial Spider run following registration, the Spider fetches the spec document and stores it as the registered spec snapshot. All subsequent Spider runs compare the live document at spec.url against this snapshot to detect breaking changes (S-3 assessment). The snapshot is updated when the Service Owner submits an APM update that increments api_version.
An APM update that changes spec.url MUST trigger immediate Spider re-verification and snapshot replacement (see Section 5.1).

The service_id MUST be stable across re-registrations and version updates. It is the canonical identity of the service in the APIX and MUST be a UUID v4 or an APIX-issued deterministic identifier.

Protocol Type Registry (v1.0 starter set) The spec.type field MUST contain a value from the Protocol Type Registry at apix.example.org/registry/protocols. The registry is the authoritative and always-current list of valid values. The entries below are the v1.0 starter set for API services; the governing body extends the registry as additional protocol types reach sufficient adoption. Registry entries follow the lifecycle defined in .

Registry value	Standard	Spider behaviour	Status
`openapi`	OpenAPI 3.x	Parses paths, schemas, auth requirements	active
`mcp`	Model Context Protocol	Parses tool definitions and capability list	active
`asyncapi`	AsyncAPI 2.x / 3.x	Parses channels, message schemas	active
`graphql`	GraphQL SDL	Introspection query to `entry_point`; see below	active

Note: IoT device service types (device-class, hub) are defined in and are not governed by this profile.

GraphQL Spider Behaviour For services with spec.type: graphql, the spec.url field MUST point to the GraphQL endpoint (identical to entry_point in most deployments). The Spider MUST issue a standard GraphQL introspection query to that endpoint: The Spider MUST POST this query as Content-Type: application/json with {"query": "<introspection query>"}. A 200 response with a valid JSON body containing a data.__schema object constitutes a successful spec fetch (S-2 prerequisite). Normalised schema representation: The Spider MUST normalise the introspection result into a canonical form before storage as the registered spec snapshot. The canonical form is a sorted JSON object containing:

types: alphabetically sorted list of non-introspection type names (excluding built-in scalar and introspection types: __Schema, __Type, __TypeKind, __Field, __InputValue, __EnumValue, __Directive, __DirectiveLocation, Boolean, Int, Float, String, ID)
Per type: kind, sorted fields list, per field: name, required/optional status, argument names and types, return type name

Normalisation eliminates cosmetic differences (field order, whitespace) from breaking change detection. Breaking change definition for GraphQL:

Change	Breaking
Removed type	Yes
Removed field on existing type	Yes
Added required argument to existing field	Yes
Changed return type of existing field	Yes
Added optional field	No
Added new type	No
Added optional argument	No
Deprecated field (marked `isDeprecated: true`)	No — recorded as metadata warning only

Introspection disabled: Some production GraphQL services disable introspection as a security measure. If the introspection query returns an error (HTTP 200 with {"errors": [...]} containing a message indicating introspection is disabled, or HTTP 4xx), the Spider MUST set spec_consistency: unreachable and record a metadata warning with code graphql_introspection_disabled. The service CANNOT achieve S-2 without enabling introspection for the Spider's IP range, or by providing an alternative static SDL document at a dedicated spec.url (in which case spec.type MUST be graphql and the Spider will fetch and parse the SDL document directly instead of issuing the introspection query). Services whose specification type is not yet in the registry SHOULD request addition via the governing body's registry extension process before registering. Until the type is added, such services cannot achieve S-2 or above, as the Spider has no parser for unregistered types.

Capability Taxonomy Registry (v1.0 starter set) The capabilities field MUST contain terms from the Capability Taxonomy Registry at apix.example.org/registry/capabilities. The registry is the authoritative and always-current list of valid terms. Terms are hierarchical, dot-separated (e.g., commerce.marketplace), and follow the lifecycle defined in . The following are the v1.0 starter set for API services. IoT-specific capability terms (iot, home.*) are defined in . The live registry is the authoritative source; this list is illustrative only.

Term	Description	Status
`commerce`	E-commerce and marketplaces	active
`commerce.marketplace`	Multi-vendor marketplace	active
`commerce.retail`	Single-vendor retail	active
`payments`	Payment processing	active
`payments.card`	Card payment processing	active
`payments.crypto`	Cryptocurrency payments	active
`data.financial`	Financial data and markets	active
`data.legal`	Legal documents and data	active
`nlp`	Natural language processing	active
`nlp.translation`	Language translation	active
`identity`	Authentication and identity	active
`communication`	Messaging and notifications	active
`storage`	File and object storage	active
`compute`	Code execution and computing	active
`media`	Image, audio, video services	active
`search`	Information retrieval	active

A Service MUST declare at least one capability term. Declared capabilities are validated by the Spider against the parsed specification where the spec type supports it. Services using deprecated taxonomy terms receive a standard_warnings entry in their Service Record.

Hierarchical semantics Capability terms form a strict containment hierarchy expressed by their dot-separated segments. A term is a sub-capability of every term obtained by removing one or more trailing segments: payments.card is a sub-capability of payments; logistics.tracking.express is a sub-capability of both logistics.tracking and logistics. Equivalently, declaring a service under a term asserts that the service is an instance of every ancestor term (is_instance_of). Containment MUST be evaluated on whole dot-separated segments, never on raw character prefixes. A term T contains a term U if and only if U equals T, or U begins with T immediately followed by a . separator. Thus payments contains payments.card but does not contain a distinct term that merely shares a leading substring. A service that declares a sub-capability is discoverable under every ancestor term without separately declaring the ancestors; ancestor expansion is performed by the index, not by the registrant. This hierarchy is the basis for hierarchical capability search (see the capability search parameter) and for graph-based discovery.

Capability Taxonomy Governance The Capability Taxonomy Registry is maintained by the governing body. The following process governs additions, deprecations, and removals: Proposing new terms: Any organisation may propose a new taxonomy term. A proposal MUST include: a candidate term (dot-separated, max 4 levels), a definition (max 200 words), examples of services that would use it, and evidence of adoption (at minimum 3 registered or planned APIX services that require the term). Proposals MUST be submitted via the governing body's designated public proposal mechanism. Review cycle: the governing body reviews taxonomy proposals quarterly. A proposal is accepted when: the definition is unambiguous, the term does not overlap with an existing term, and the adoption evidence is credible. Accepted terms are added as active in the next quarterly registry update. Versioning: The Capability Taxonomy Registry is independently versioned. The registry version is exposed in the APIX root resource (see Section 9.2). The taxonomy version advances on any addition or deprecation. Deprecation: A term is deprecated when a more precise replacement term is accepted. Deprecation follows the lifecycle defined in Section 4.3: 12-month minimum window, 90-day grace period. IANA considerations: The taxonomy is not maintained by IANA. The governing body is the designated authority. Should a future version of this specification transfer maintenance to IANA, a mapping document MUST be published.

Notification Channel Registry (v1.0 starter set) The notifications.channels[].type field MUST contain a value from the Notification Channel Registry at apix.example.org/registry/notification-channels. The following are the v1.0 starter set. Registry entries follow the lifecycle defined in .

Registry value	Transport	Direction	Applicable to	Semantics
`webhook`	HTTPS POST	Server → agent	All service types	Service posts event payloads to an agent-registered callback URL. Agent provides the callback URL at subscription time via the `registration_url` endpoint. The service MUST include a shared secret in each delivery; agents MUST verify it. At-least-once delivery; agents MUST be idempotent.
`sse`	HTTP Server-Sent Events	Server → agent	API services only	Agent opens a long-lived HTTP GET connection to the service's event stream. No subscription management endpoint required; the `registration_url` field carries the SSE stream URL. Agent reconnects on disconnect per the SSE specification ().
`websocket`	WebSocket (RFC 6455)	Bidirectional	API services only	Agent opens a WebSocket connection to the service. `registration_url` is the WebSocket endpoint. Enables request/response and push notification in a single persistent connection.

Subscription management: For webhook, the registration_url MUST point to an HTTPS endpoint that accepts a subscription registration payload. The minimum subscription registration format is: The registration endpoint MUST return the subscription identifier and expiry time. Agents are responsible for renewing subscriptions before expiry. Event types: The events field in the APM notification channel and in subscription requests MUST contain values from the APIX Event Type Registry at apix.example.org/registry/event-types. The v1.0 starter set:

Event type	Description
`spec.updated`	The service's spec document has changed (new `api_version`)
`status.changed`	Service operational status has changed (up/down/degraded)
`trust.changed`	Organisation or service trust level has changed

Notification channel requirements are OPTIONAL for registration. Services that do not support push notifications MUST set notifications.supported to false. Consuming agents that require push notifications SHOULD filter by notifications.supported: true before subscribing.

Registration and Onboarding

Push Registration (Human-Initiated) Service registration MUST be human-initiated. The registrant MUST agree to the index operator's Terms of Service before any service record is activated. For O-0 and O-1, self-service portal registration with accepted Terms of Service satisfies this requirement. For O-2 and above, registration MUST additionally involve a formal B2B contractual relationship between the Service Owner and the index operator or its Accredited Regional Representative. Registration MUST be scoped at the organisation level. An organisation registers once and undergoes identity verification once; multiple services may then be registered under that organisational identity. This requirement ensures:

Identity verification and sanctions screening are performed once per legal entity, not repeated per service.
Organisation trust (O-level) established at registration propagates to all services registered under that organisation without re-verification of the organisation's identity.

Definition: one service equals one APIX Manifest (APM) document with one distinct entry_point. Logical bundling of API paths under a single entry point is the registrant's responsibility and is permitted. The registration process:

The Service Owner (or their Accredited Regional Representative) creates an Organisation Account in the APIX Registration Portal. The index operator MUST screen the Service Owner against applicable sanctions lists before account activation per .
The Service Owner provides organisation details sufficient for the target Organisation trust level. This step is performed once per organisation.
The Service Owner submits an APIX Manifest for each service to be registered, including the spec URL and entry point. Each service is associated with a liveness monitoring configuration that determines Spider check frequency (see Section 5.3).
For O-1: email and domain ownership verification is completed automatically.
For O-2: the index operator or Regional Representative verifies the declared company registration number.
For O-3: APIX automatically checks security.txt, DMARC/SPF records, and declared legal document URLs. No human review required.
For O-4 and O-5: the Service Owner engages an Accredited Verifier (O-4) or submits an audit certificate directly to the governing body (O-5).
Upon completion of applicable checks, the service is activated in the index and the Spider is triggered.

Accredited Verifier Requirements Organisation levels O-4 and O-5 require an Accredited Verifier. To be accredited by the governing body, a candidate Verifier organisation MUST satisfy all of the following: Independence: The Verifier MUST have no ownership relationship, employment relationship, or consulting engagement with any organisation it assesses. Independence is evaluated per assessment: a Verifier that provided consulting services to the candidate organisation within the prior 24 months MUST recuse itself from that assessment and the governing body MUST assign an alternate Verifier. Demonstrated audit competence: The Verifier organisation MUST hold at least one of: ISO/IEC 27001 Lead Auditor certification (per ISO/IEC 17021), SOC 2 attestation authority (AICPA CPA firm licensed for attestation engagements), or ISAE 3402 Type II authority. At least one named individual from the Verifier organisation MUST hold a current relevant professional certification (CISA, CISSP, or equivalent recognised by the governing body). APIX trust level: The Verifier organisation MUST itself be registered in APIX at O-2 or above. Contractual obligation: The Verifier MUST sign the Verifier Agreement, which binds it to: the Verifier Standard, liability for negligent assessments, incident reporting obligations, and annual re-accreditation. Annual review: Accreditation is reviewed annually by the governing body. Failure to maintain the requirements above or material error in an assessment MUST result in suspension pending review. The governing body MUST maintain a public registry of all accredited Verifiers and their current accreditation status. Revocation: the governing body MAY revoke accreditation at any time for material breach of the Verifier Agreement, demonstrated conflict of interest, or failure to maintain competence requirements. Revocation is immediate; pending assessments are transferred to an alternate Verifier at no additional cost to the assessed organisation.

Spider Verification (Automated) The APIX Spider is triggered automatically at two points:

At registration: once a service is activated, the Spider performs an initial verification run to establish the baseline Service Verification Level.
On schedule: thereafter, the Spider rechecks the service at the interval defined by the service's commercial tier (see Section 5.3).

During a Spider run, the Spider:

Performs an HTTPS request to {entry_point}/health and records the response code, response time, and timestamp (Liveness: S-1).
Fetches the spec document from spec.url (HTTPS, no authentication).
Parses the fetched document and compares it structurally against the registered spec snapshot (S-2 if fetchable and consistent; S-3 assessed if no breaking changes detected across three or more consecutive runs).
Updates all Liveness metrics in the Service Record.
Records any failures and increments consecutive_failures.
If the APM contains a custom field, records each declared key name in the index's custom key registry. No values are stored; the custom array contains only key name strings.

The Spider MUST NOT call any API endpoint beyond {entry_point}/health and spec.url. The Spider MUST NOT submit data to, create resources in, or otherwise interact with the production API of a registered service. The Spider MUST respect HTTP rate limits declared by the service. Spider requests MUST include a User-Agent header identifying the APIX Spider and version.

Service Verification Level Ceilings Certain service configuration states and governing body actions create hard ceilings on the maximum Service Verification Level achievable or maintainable. The following table defines all ceiling conditions for API services. The index MUST enforce these ceilings automatically.

Condition	Maximum S-level
`spec.url` requires authentication	S-1
`spec.url` unreachable or unparseable	S-1
Spec type not in APIX Protocol Type Registry	S-1
GraphQL service with introspection disabled and no SDL at `spec.url`	S-1
Fewer than three consecutive Spider runs completed	S-2
Liveness frequency set to `initial` (Spider runs once only)	S-2
Active `security_incident` flag set by governing body	S-2
No completed security scan or pen test certificate on file	S-3

security_incident is an index-maintained flag, not an APM field. It is set by the governing body upon receipt of credible breach intelligence and cleared only after the service owner demonstrates full remediation and passes a new security scan. The process for setting, contesting, and clearing this flag — including the evidence threshold, contestation procedure, and integration with external security feeds — is an open question (see Section Open Questions).

Free Registration Tier and Abuse Deterrence Service registration at O-0 and O-1 trust levels constitutes the free registration tier. No payment information is required for these levels. This is a deliberate design choice: requiring payment for O-0 would create a barrier to early adoption and conflict with the open infrastructure mission. The following controls are sufficient at the free tier:

Mandatory Terms of Service acceptance: All registrations — including free tier — require agreement to the index operator's Terms of Service before account activation. For O-0 and O-1, this self-service acceptance is the sole contractual requirement and creates legal accountability regardless of tier. For O-2 and above, a formal B2B contract is additionally required.
Sanctions screening at activation: All organisations are screened before account activation per Section 7. Sanctioned entities cannot register at any tier.
Default discovery exclusion: Consuming agents applying standard Trust Policies (org_level_min O-1 or higher) structurally exclude O-0 services from results. Abuse at O-0 cannot reach consuming agents that apply minimum recommended trust filters. Consuming agents that accept O-0 services MUST do so deliberately.
Liveness gating: O-0 services configured at initial liveness frequency are excluded from default search results by default (see Section 5.3). An abusive operator that registers a fake service and then takes it offline will be gated out by both trust filtering and liveness filtering simultaneously.

Payment information on file is NOT required for O-0 or O-1 registration. A future version of this specification MAY require payment information on file (without charge) for O-1 as an additional identity anchor if operational experience shows the above controls insufficient. This is not normative for the current version.

Liveness Monitoring Configuration Each registered API service MUST have a liveness monitoring configuration that determines Spider check frequency. This configuration:

Is set per service, not per organisation account. An organisation MAY configure different check frequencies for different services registered under the same account.
MUST be agreed in the commercial contract between the Service Owner and the index operator.
Determines the maximum age of last_ping_at data available to consuming agents for that service.

Implementations MUST support at minimum the following frequency classes, identified by their normative spider_interval value in the Service Record:

Frequency class	Maximum spider_interval	Normative label
Initial only	N/A (one run at activation)	`"initial"`
Daily	86,400 seconds	`"daily"`
Hourly	3,600 seconds	`"hourly"`
High-frequency	300 seconds	`"high"`

Implementations MAY define additional frequency classes. The spider_interval field in the Service Record MUST reflect the actual configured interval in seconds. Effect on trust signal quality: A consuming agent applying a last_ping_age < N filter will structurally exclude services whose check frequency cannot produce sufficiently fresh liveness data. Liveness monitoring configuration is therefore a market signal: services requiring discovery by latency-sensitive agents must invest in check frequency sufficient to satisfy those agents' trust policies. Services configured at initial-only frequency MUST be excluded from standard discovery query results by default. Consuming agents MUST explicitly opt in to include initial-only services in result sets.

Spider and Crawler Specification

Crawl Triggers The Spider is triggered by the following events:

Trigger	Description
Registration activation	Immediate first run when a service is activated
Scheduled interval	Recurring, per service liveness monitoring configuration (Section 5.3)
Manual re-trigger	Service Owner may request a manual re-trigger once per 24 hours
Spec URL change	An APM update that changes the `spec.url` triggers an immediate run

Automated Verification Scope The Spider performs the following checks in sequence. Each check's result is stored independently; a failure at one level does not prevent checks at other levels from being recorded. The Spider MUST use HTTPS for all outbound requests. The Spider MUST NOT send authentication credentials to any registered service. Spider requests to entry_point/health or spec.url MUST NOT include Authorization headers, API keys, cookies, or client certificates. If a request returns an HTTP redirect (3xx), the Spider MUST follow the redirect only if the redirect target also uses HTTPS. The Spider MUST NOT follow redirects from HTTPS to HTTP.

Liveness check: HTTPS GET to {entry_point}/health. Record HTTP status code, response time, and timestamp. A 2xx response without authentication constitutes a successful liveness check (S-1). If the response body is valid JSON containing an api_version field, the Spider MUST cross-check this value against the api_version declared in the APM. A mismatch is recorded as a metadata warning, not a liveness failure.
Spec fetch: HTTPS GET to spec.url. The Spider MUST NOT send authentication credentials. A successful fetch (2xx response, non-empty body) is the prerequisite for steps 3 and 4. Record content type and document size.
Spec parse and consistency check: Parse the fetched document according to the declared spec.type. Compare it structurally against the registered spec snapshot stored at initial registration time. The Spider MUST set spec_consistency to one of three values after every run:
- consistent — document is fetchable, parseable, and structurally matches the registered snapshot. Constitutes S-2 verification.
- mismatch — document is fetchable and parseable, but structurally differs from the snapshot (paths removed, required fields changed, response schemas changed). S-2 is revoked; standard_warnings is updated. This indicates operator-caused contract breakage.
- unreachable — spec.url returned a non-2xx response, was not reachable, or the document could not be parsed. S-2 is not achieved or is suspended. This indicates an availability problem, not a contract violation. spec_consistency MUST be null only before the Spider's first run on a newly registered service. Once any run completes, the field MUST carry one of the three values above. The Spider MUST NOT call any API endpoint declared in the spec. Spec verification is document comparison only.
Breaking change detection: Compare the current parsed spec against the registered spec snapshot. Flag removed paths, changed required fields, or changed response schemas as breaking changes. Three or more consecutive runs with no breaking changes detected are required for S-3 verification.
Liveness metrics update: Update last_ping_at, uptime_30d_percent, avg_response_ms, consecutive_failures, and next_spider_run_at.

Failure Handling Liveness failures (entry_point/health unreachable):

A single failed ping increments consecutive_failures and updates last_ping_at with the failure timestamp.
After 3 consecutive failures, the Service Record is flagged as status: degraded in the index.
After 10 consecutive failures, the Service Record is flagged as status: unreachable and is excluded from standard search results.
contacts.operations is notified at the 3-failure threshold (incident warning). Both contacts.operations and contacts.escalation are notified at the 10-failure threshold (service unreachable escalation).
A service that recovers (next ping succeeds) has its status restored and consecutive_failures reset to 0 automatically.

Spec fetch failures (spec_consistency: unreachable): Spec fetch failures have distinct probable causes depending on how long the failure persists. The Spider MUST apply a three-cluster retry model that targets the likely cause window at each stage. Cluster escalation is triggered by spec_fetch_consecutive_failures crossing a threshold.

Cluster 1 — Infrastructure / network (failures 1–3):: Cause: transient network loss, host restart, or CDN hiccup. Retry: 5 min → 15 min → 30 min. No notification.
Cluster 2 — Application (failures 4–6):: Cause: software instability (crash loop, OOM, startup failure). Retry: 2 h → 4 h → 8 h. Notification: email to contacts.operations at failure 4.
Cluster 3 — Configuration (failures 7+):: Cause: persistent misconfiguration — wrong spec.url, auth gate added, URL moved. Retry: 24 h → 72 h (cap). Notification: email to contacts.operations AND contacts.escalation at failure 7.

spec_consistency is set to unreachable on the first failure and remains unreachable until a successful fetch.
next_spider_run_at is set to the next retry timestamp after each failed run so Service Owners can observe when the retry will occur.
A successful spec fetch resets spec_fetch_consecutive_failures to 0 and sets spec_consistency to consistent or mismatch as appropriate.
spec_fetch_consecutive_failures MUST be visible in the Service Record so Service Owners can monitor retry cluster state without contacting the Index operator.

Manual re-trigger: The Index operator SHOULD provide a mechanism for Service Owners to request an immediate Spider re-run outside of the scheduled interval. This is the primary recovery mechanism when a service has been repaired and the operator does not want to wait for the next scheduled retry. When a manual re-trigger is requested: - next_spider_run_at MUST be set to the current timestamp. - spec_fetch_consecutive_failures MUST be reset to 0, returning the service to Cluster 1 retry behaviour for the next run. - The Spider MUST execute the run as soon as scheduling permits. The Index MAY rate-limit manual re-triggers to at most once per hour per service to prevent abuse.

Index API — Services Layer

Search and Filter API The search endpoint applies server-side filters to reduce result sets before transmission. Only filters on indexed scalar values are server-side; filters requiring deep metadata evaluation are applied client-side after fetching the Level 2 Service Record (Section 7.4). API version scoping (path segment): The optional {api_version} path segment scopes the search to services whose api_version starts with the specified major or major.minor prefix. The segment uses the v prefix followed by the semver major or major.minor value (e.g., v2, v2.4). When absent, no version constraint is applied. The api_version immutability invariant (see ) means that a consuming agent pinned to /search/v2.4/ receives a stable, permanent schema contract: every result exposes exactly the fields defined for v2.4. The index does not perform cross-version mapping. A service registered at v3.0 does not appear in /search/v2/ results and is never synthesised into a v2-shaped response. There are no null substitutions for dropped fields and no type coercions for changed fields across version boundaries. If a pinned-version query returns empty results, the agent SHOULD follow the superseded_by link in any previously known Level 2 record to discover the current version, or issue GET /search/ with no path segment and no query parameters to retrieve the version landscape (see ). The parameter-less /search/ endpoint returns version metadata only and executes no content query — it is a discovery resource, not a full-index dump. Example — buying bot querying for marketplace services: Version landscape response (GET /search/ — no path segment, no query parameters): When the search endpoint is called with no api_version path segment and no query parameters, it MUST return the version landscape and MUST NOT return service records: Consuming agents that receive empty results from a pinned-version query MUST use this endpoint to survey the current version landscape before re-issuing a content query. The _links.search template in each entry provides the correctly scoped search URL for that version prefix. Normative server-side filter parameters:

Parameter	Type	Default	Description
`q`	string	—	Free-text search across `name` and `description`
`capability`	string	—	Capability taxonomy term. MUST be an `active` or `deprecated` registry value. Matched hierarchically by default — see "Hierarchical capability matching" below
`capability_match`	enum	`subtree`	Capability match mode: `subtree` returns the term and all its sub-capabilities; `exact` returns only services declaring the exact term
`filter_strictness`	enum	`graceful`	Validation behaviour for filter values. `graceful`: an invalid filter value is ignored (treated as unset) and reported in `_meta.warnings`; `strict`: an invalid filter value rejects the request with `400 Bad Request`
`protocol`	string	—	Comma-separated protocol type values. MUST be values from the Protocol Type Registry
`org_level_min`	enum	`O-0`	Minimum Organisation trust level. Excludes services below threshold
`service_level_min`	enum	`S-0`	Minimum Service verification level
`max_ping_age`	integer	—	Maximum seconds since `last_ping_at`. Excludes services with older liveness data
`uptime_30d_min`	float	—	Minimum 30-day uptime percentage
`lifecycle_stage`	enum	`stable`	Filter by lifecycle stage. Default excludes `experimental`, `beta`, `deprecated`, and `sunset`
`include_superseded`	boolean	`false`	When `false`, excludes services for which `superseded_by` is set. When `true`, all matching versions are returned
`spec_consistency`	enum	—	Filter by spec consistency status. Values: `consistent`, `mismatch`, `unreachable`. `null` (Spider not yet run) is excluded when any value is specified. When absent, no constraint is applied. Agents performing consequential tasks SHOULD explicitly pass `consistent`
`language`	string	—	BCP 47 language tag (). Returns only services whose `language` array contains the specified tag. Services with no `language` field are treated as `["en"]`
`pricing_model`	enum	—	Filter by declared pricing model. Values: `free`, `freemium`, `paid`, `enterprise`, `dynamic`. When absent, no pricing constraint is applied
`auth_method`	enum	—	Filter by supported authentication method. Values: `oauth2`, `api_key`, `bearer`, `mtls`, `none`. Returns services whose `authentication.methods` array contains the specified value
`deployment_region`	string	—	Cloud or jurisdiction region identifier (e.g. `eu-west-1`, `eu`). Returns only services that declare the specified region in `deployment_regions`. Candidate field — see Open Question 8
`near`	string	—	Decimal `lat,lon` coordinate pair (e.g. `48.137,11.576`). When combined with `coverage_radius_km`, returns only services whose declared coverage area overlaps the specified point. Candidate field — see Open Question 8
`coverage_radius_km`	integer	—	Radius in kilometres around the `near` coordinate. Only meaningful when `near` is also specified. Candidate field — see Open Question 8
`custom_key`	string	—	Reverse-domain key name (e.g. `com.example.coverage_polygon`). Returns only services whose `custom` object contains the specified top-level key. Values are not searchable; key presence only
`fresh_within`	duration	—	Maximum age of `last_verified_against_target` (e.g. `7d`, `24h`). Returns only services whose self-reported verification timestamp falls within the window. Services without the field are excluded when this parameter is present
`verification_basis`	string	—	Filter by the Organisation trust level's evidence basis. MUST be a Verification Basis Registry value (e.g. `eidas2_qeaa`, `cra_conformity`). Matches the recorded evidence channel
`page`	integer	`1`	Result page number
`page_size`	integer	`20`	Results per page. Maximum: 100

All filter parameters are OPTIONAL. When absent, the parameter imposes no constraint except lifecycle_stage (default stable), include_superseded (default false), and capability_match (default subtree). Hierarchical capability matching. A ?capability=T query MUST return every service whose declared capabilities array contains T or any sub-capability of T, using the whole-segment containment rule defined under "Hierarchical semantics" in the Capability Taxonomy Registry section. For example, ?capability=payments MUST return services that declared payments.card or payments.crypto, not only those that declared payments exactly. Setting capability_match=exact restricts the result to services declaring T exactly. Ancestor expansion is performed by the index at query time; a service need not declare ancestor terms to be discoverable under them. Filter validation and result warnings. The index validates every filter value that references a registry (capability, protocol, verification_basis, …) or a closed enum. Two outcomes are signalled back to the consuming agent so that neither a deprecated nor an invalid filter fails silently:

A deprecated-but-valid value (e.g. a capability term in its warning period) is honoured normally and reported with a deprecated warning, including sunset_date and replacement. A deprecated value is never rejected: filter_strictness governs invalid values only, so a strict query never short-circuits the deprecation window's grace period.
An invalid value (not present in the relevant registry or enum, e.g. verification_basis=wishful_thinking) is handled according to filter_strictness:
- graceful (default): the offending filter is ignored — treated as unset — and reported with an invalid warning. The query proceeds with the remaining valid filters. This prevents the silent-failure trap in which an agent believes a constraint was applied when it was not.
- strict: the index rejects the request with 400 Bad Request; the response body names each invalid parameter and value.

Warnings are returned in a _meta.warnings array on the search response envelope, alongside the existing _links: An index MAY additionally emit a lightweight APIX-Warning response header carrying the warning count as a fast signal; the authoritative warning detail is always the _meta.warnings array. The obsolete HTTP Warning header () MUST NOT be used for this purpose. Results are returned as paginated Level 1 Search Result records (Section 7.2) with HATEOAS links to Level 2 Service Records. Pagination is REQUIRED. Design note — natural language search is out of scope for the base specification: The APIX search endpoint provides keyword and structured-filter search only. Semantic or natural-language query processing — where a free-text prompt such as "find me a low-latency European payment API that handles refunds" is resolved to a ranked service list by embedding or language model inference — is explicitly excluded from this version of the specification. The I-D draft-cui-ai-agent-discovery-invocation () describes this pattern as an optional registry capability (MAY); APIX does not exercise this option in the base specification for the reasons stated below. Two factors motivate this exclusion. First, semantic search is computationally expensive at index scale: inference on every incoming query creates a load profile incompatible with the latency and cost targets of a globally shared, freely accessible discovery endpoint. Second, short free-text queries — the form agents will most commonly submit — are insufficient input for embedding-based retrieval to reliably outperform structured keyword and capability-taxonomy filters; the signal-to-noise ratio degrades rapidly below approximately 50 tokens of context, producing ranking instability that would erode agent trust in the index. The q parameter (free-text across name and description) combined with the structured filters defined above covers the precision requirements of well-formed agent queries. Agents requiring relevance ranking beyond what structured filters provide SHOULD perform client-side re-ranking over a filtered candidate set fetched from the index. Agents requiring semantic selection over a filtered candidate set are encouraged to implement — or delegate to — a Semantic Routing Platform (SRP) as described in draft-cui-ai-agent-discovery-invocation (): an optional control-plane layer that performs semantic matching and ranking against a structured candidate pool. APIX is the natural source for that pool; an SRP queries APIX with structured filters to obtain a trusted, governed candidate set and then applies semantic ranking above that foundation. This separation keeps index infrastructure costs predictable while enabling full semantic selection capability for agents that need it. A future premium tier of the APIX MAY introduce semantic search as a priced capability (charged per request) once a quality and cost model acceptable to the governing body and the operator community has been established. Any such capability would be offered as an optional endpoint and would not alter the behaviour of the base search endpoint defined in this specification.

Search Result Schema (Level 1) Search results return lightweight summary records. These contain only the fields needed to evaluate candidates and decide which detail pages to fetch. Complex metadata (auth requirements, version history, notifications, legal, standard_warnings) is available only at Level 2 and is evaluated client-side after fetching the detail resource. The latest_stable link points to the leaf version of the service's version chain. When latest_stable differs from self, a newer stable version exists and the agent SHOULD follow the link before proceeding.

Service Record Schema (Level 2) The full Service Record is returned when a consuming agent fetches the detail resource via the self link. It is the APM plus Spider-enriched trust metadata, versioning links, and any standard_warnings.

Trust Metadata Schema Trust metadata is always included in full Service Records (Level 2) and MUST NOT be omitted or summarised. Consuming agents rely on the full set of trust fields to evaluate their Trust Policy. Partial trust metadata MUST be represented with explicit null values, not omitted fields. Trust metadata is included in summary form (Level 1) for server-side filter compatibility. The Level 1 trust object omits verification timestamps and verifier IDs; these are available only at Level 2.

Verification Basis Registry The trust.organisation_verification_basis field records which evidence channel substantiated the Organisation trust level. It is set by the index, not self-declared. This lets consuming agents that operate under specific regulatory regimes filter by the provenance of a trust level — for example, preferring an O-2 substantiated by an EU-anchored credential over one substantiated by an arbitrary national registry. The registry is maintained by the governing body. The v1.0 starter set:

Value	Applies to	Evidence channel
`national_registry`	O-2	Company registration number confirmed against an official national registry
`gleif_lei`	O-2	Legal Entity Identifier verified against the GLEIF LEI database
`eidas2_qeaa`	O-2	Qualified Electronic Attestation of Attributes from a Qualified Trust Service Provider per Regulation (EU) 2024/1183 (eIDAS 2)
`soc2_type2`	O-5	SOC 2 Type II audit certificate
`iso27001`	O-5	ISO/IEC 27001 certification
`cra_conformity`	O-5	Conformity assessment under Regulation (EU) 2024/2847 (Cyber Resilience Act)

The field is OPTIONAL and MAY be null for trust levels where the basis is not recorded (O-0, O-1) or not yet captured. Governance. The Verification Basis Registry lives at apix.example.org/registry/verification-basis and is maintained by the governing body following the same proposal, quarterly-review, versioning, and deprecation process defined for the Capability Taxonomy Registry: any organisation MAY propose a new evidence channel with a definition, the applicable O-level, and adoption evidence; accepted values are added as active in the next quarterly update; superseded values are deprecated under the lifecycle. The registry is independently versioned and its version is exposed in the APIX root resource. IANA considerations. This registry is not maintained by IANA. The governing body is the designated authority. Should a future version of this specification transfer maintenance to IANA, a mapping document MUST be published.

Transport Encoding The Index API is consumed by autonomous agents at machine speed. Response payloads are structured JSON with highly repetitive field names across result arrays. Transport-layer compression achieves 70–85% size reduction on typical search result payloads with no information loss and no application-layer schema changes. Compression support requirements: The Index API MUST support the following Accept-Encoding values:

Encoding	Requirement	Notes
`gzip`	MUST	Universally supported baseline
`br` (Brotli)	SHOULD	Higher compression ratio than gzip
`zstd`	SHOULD	Similar ratio to Brotli; faster decompression

The Index API MUST perform content negotiation via the Accept-Encoding request header. Responses MUST include a Content-Encoding header identifying the applied encoding. If a client sends no Accept-Encoding header, the server MAY respond uncompressed. Consuming agents SHOULD include Accept-Encoding: zstd, br, gzip in all Index API requests. Binary encoding (optional): The Index API MAY additionally support CBOR () as a binary alternative to JSON. A client that prefers CBOR MUST signal this via Accept: application/cbor. The server MAY respond with Content-Type: application/cbor. CBOR responses carry identical information to JSON responses; the encoding difference is transparent to the data model. Clients MUST NOT assume CBOR support. JSON over compressed transport is the normative interchange format.

Security Considerations

Abuse and Fake Listings The mandatory Terms of Service acceptance at registration provides a first barrier against malicious actors listing fake or harmful services. For O-0 and O-1, identity verification is limited; consuming agents SHOULD NOT rely solely on index presence for trust at these levels. For O-2 and above, the formal B2B contractual relationship and progressively stronger identity and compliance verification substantially raise the cost of abuse. Consuming agents SHOULD apply Trust Policies that exclude O-0 services for any task involving sensitive data or consequential actions. The governing body MUST maintain an abuse reporting mechanism and MUST be able to suspend or remove a Service Record within 24 hours of confirmed abuse. Suspended service records MUST remain in the index with a status: suspended flag and MUST NOT be silently deleted, to provide transparency to agents that had cached the record.

Trust Level Spoofing Organisation and Service trust levels in the Service Record are set only by the APIX itself, not by the Service Owner. APM submissions that include trust field values MUST have those values overwritten by the APIX upon processing. The Index API MUST NOT expose self-asserted trust values.

Transport Security Requirements All URLs submitted as entry_point or spec.url values in an APM MUST use the https scheme. The Index MUST reject APM submissions that provide HTTP (non-TLS) values for these fields. The {entry_point}/health endpoint MUST NOT require authentication of any kind. Requiring authentication at /health defeats liveness verification and MUST be treated as a registration defect. The Index MUST record a metadata warning if the /health endpoint returns a 401 or 407 status. The spec.url endpoint MUST be publicly accessible without authentication. A spec.url that requires authentication cannot be verified by the Spider and MUST be treated as an S-2 failure until authentication is removed. The Spider MUST enforce HTTPS for all outbound requests and MUST NOT follow redirects from HTTPS to HTTP.

Spider-Targeted Attacks A service that knows when the Spider will visit could serve compliant responses only to Spider requests, presenting a different interface to consuming agents. Mitigations:

Spider visit timing MUST be randomised within the liveness monitoring interval window.
Spider User-Agent headers MUST be versioned but MUST NOT include the specific visit schedule.
The APIX operator SHOULD perform periodic unannounced spot-checks from non-Spider infrastructure.

Bot Consumer Risks The APIX provides discovery and trust metadata. It does not guarantee the safety, correctness, or availability of listed services. Consuming agents MUST NOT assume that a service listed in the APIX is safe to use without applying their own Trust Policy. Consuming agents SHOULD treat Index API responses as untrusted input and validate the structure of Service Records before acting on them. The Index API MUST be served exclusively over TLS. Certificate validity MUST be verified by consuming agents. Agents MUST NOT bypass TLS certificate verification when querying the Index API.

Open Questions The following questions are unresolved and explicitly invited for community input:

APM spec type extensions: What is the formal process for registering new spec.type values? Should this be an IANA registry, or remain under the governing body governance analogous to the capability taxonomy process?
Trust Policy standardisation: Should the APIX define a standard Trust Policy expression language, or leave this entirely to consuming agents? A standard language would enable Index API server-side filtering but risks constraining agent-side policy flexibility.
Regional Representative model: How are jurisdictional boundaries defined for Regional Representatives? What happens in jurisdictions with no appointed Representative — does the central index operator serve as fallback, or is registration simply unavailable?
Bot identity: This document explicitly excludes bot identity from scope. Should a future version of the APIX include optional bot consumer registration to enable personalised discovery, rate limit management, or abuse tracking?
Centralised index vs. decentralised discovery: The APIX architecture takes a deliberate position: a single authoritative global index, governed by a neutral non-profit, with a commercial sustainability model. An alternative approach — represented by proposals such as draft-vandemeent-ains-discovery (AINS — AInternet Name Service), which uses signed, append-only replication logs with no central authority — takes the opposite position: cryptographic verifiability and censorship resistance over governed accountability. Arguments for the APIX model: business adoption requires a contractual counterparty; institutional co-sponsorship is only available to an accountable entity; a single entry point minimises agent-side integration complexity; the supply-side funding model creates a regional development flywheel that decentralised models cannot replicate. Arguments for the decentralised model: censorship resistance; no single point of failure or organisational control; cryptographic verifiability without trusting the governor. Community input is explicitly invited on whether the APIX and AINS-style approaches are mutually exclusive or whether a future APIX version could expose a verifiable, signed export of index records that enables third-party verification without requiring a federated registry.
Geographic distribution of the index infrastructure: This specification defines a single globally stable root entry point (https://apix.example.org/) and leaves index deployment topology to the operator. A conformant implementation MAY use CDN edge nodes, read replicas, or geographically distributed origin servers provided the HATEOAS link structure and the canonical entry-point URL remain stable. The specification intentionally does not mandate a replication or failover architecture: these are operational concerns for the governing body as index operator. A future operational profile MAY specify minimum availability, recovery time objectives, and regional failover requirements.
Breach-driven trust degradation and security feed integration: This specification defines a security_incident flag that caps a service at S-2 while active. The following questions are unresolved and invited for community input:
- Evidence threshold: What constitutes sufficient evidence for the governing body to set the security_incident flag? A confirmed breach notification from the service owner, a credible third-party report, or an entry in a recognised security feed (BSI, CISA KEV, CERT-Bund, or equivalent national CERT)?
- Feed integration: Should APIX consume external security feeds automatically to detect affected services, or require human review before setting a flag? Automated feed integration requires APIX to maintain knowledge of software stacks and versions per service — information not currently indexed.
- Aftermath window: Should a service that has suffered a confirmed breach be required to remain at a degraded trust level for a minimum period after remediation is declared (analogous to a probationary period), or does passing a new security scan immediately restore the full S-level? If a minimum period applies, what is the appropriate duration and who determines it?
- Contestation process: What is the process by which a service owner can contest a security_incident flag they believe was set in error?
- Real-time attack detection: The current model is retrospective — the flag is set after a breach is confirmed. Should a future version define a real-time signal path (for example, a service owner-initiated incident declaration that immediately and automatically caps the S-level) to allow proactive trust degradation during an active attack, before a formal breach is confirmed?
Dynamic pricing negotiation: This specification defines the "dynamic" pricing model with a pricing_endpoint that agents query to obtain the current price before invocation. The current model is accept-or-abandon: the agent queries the price, compares it against its budget ceiling, and either proceeds or abandons the invocation. A richer interaction model is conceivable — particularly for IoT services where load-based pricing varies continuously — in which an agent can submit a counter-offer (maximum acceptable price), request scheduling at a lower-load time window, or enter a brief negotiation exchange before committing to an invocation. Such a negotiation protocol would require a standardised request/response schema beyond the current pricing endpoint response, and potentially a reservation or commitment mechanism to hold a quoted price while the agent confirms with its operator. Community input is invited on whether dynamic pricing negotiation should be standardised in a future revision of this specification, and on the appropriate protocol model (synchronous counter-offer, asynchronous scheduling request, or market-based auction).
Deployment region and service coverage area: Service geography is two distinct concepts that the current APM schema does not distinguish, and both are increasingly relevant for agent-driven discovery. Deployment region is a data-residency and compliance concept: in which cloud regions or legal jurisdictions does the service process and store data? This matters for GDPR controller obligations, data localisation regulations, and enterprise procurement rules that prohibit cross-border data transfer. A service deployed exclusively in eu-west cannot lawfully serve queries whose data must not leave the European Economic Area. Service coverage area is a relevance concept: for which geographic area does the service actually provide value, independent of where its infrastructure runs? A regional organic food delivery platform running on US-hosted cloud infrastructure is still only useful to buyers and sellers located within its delivery catchment. An agent sourcing local produce for a household in Munich has no use for a service whose coverage area is the Pacific Northwest, regardless of that service's technical availability. Coverage area is a statement about the service's value proposition, not its infrastructure topology. For sustainability-oriented use cases — such as minimising transport distance as a proxy for carbon footprint — the coverage area radius directly determines whether a service is a candidate for selection at all. The two concepts can diverge: a globally deployed CDN-backed service may have a coverage area restricted to a single city; a locally hosted service may lawfully serve any jurisdiction. Conflating them into a single region field would produce incorrect filtering in both directions. A candidate schema extension would introduce two optional fields in the APM: json "deployment_regions": ["eu-west-1", "eu-central-1"], "coverage": { "type": "radius", "center": { "lat": 48.137, "lon": 11.576 }, "radius_km": 150 } or alternatively a GeoJSON polygon for irregular coverage areas. Corresponding search parameters (deployment_region, near, coverage_radius_km) would allow agents to filter by both dimensions independently. Community input is invited on: (a) the appropriate geometry primitives for coverage area (radius, bounding box, GeoJSON polygon, or NUTS/ISO 3166-2 administrative codes); (b) whether deployment region should reference cloud provider region identifiers or legal jurisdiction codes; (c) how coverage area interacts with the existing capability taxonomy for services where proximity is intrinsic to the capability (local logistics, in-person services, regional marketplaces); and (d) whether coverage area belongs in the base APM or as a profile extension.

Event type	Description	Status
`spec.updated`	Service spec document changed (new `api_version`)	active
`status.changed`	Service operational status changed	active
`trust.changed`	Organisation or service trust level changed	active

Registry value	Applies to	Evidence channel	Status
`national_registry`	O-2	Official national company registry	active
`gleif_lei`	O-2	GLEIF Legal Entity Identifier	active
`eidas2_qeaa`	O-2	QEAA from a Qualified Trust Service Provider, Regulation (EU) 2024/1183	active
`soc2_type2`	O-5	SOC 2 Type II audit	active
`iso27001`	O-5	ISO/IEC 27001 certification	active
`cra_conformity`	O-5	Conformity assessment under Regulation (EU) 2024/2847 (CRA)	active