backend-sdk HTTP contracts
Supported HTTP operations, source validators, SDK companions and explicit OpenAPI schema limits.
Supported HTTP operations, source validators, SDK companions and explicit OpenAPI schema limits.
These HTTP contracts are an explicit supported subset, not the whole Core API. Prefer the SDK when it exposes the operation. Authentication schemes are alternatives, not interchangeable tokens. Use the documented consumer context or CLI exchange; never send a raw maker credential as a consumer token. Read the owning guides for permissions, confirmation and asynchronous completion.
PUT /management/businesses/{businessId}/resources/{resource}/count
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"requestValidator": {
"name": "resourceCountBodySchema",
"source": "apps/core/src/routes/management/resource-counts.ts#L27",
"declaration": "const resourceCountBodySchema = z.object({\n subscriptionId: z.string().min(1),\n environmentId: z.string().min(1).nullable().optional(),\n count: z.number().int().nonnegative(),\n subjectType: z.string().min(1).max(64).optional(),\n subjectId: z.string().min(1).max(160).optional(),\n});"
},
"note": "No public SDK method for this management operation. PUT the validator's JSON fields using the documented management credential context. Success returns { resourceCount: row }; OpenAPI does not specify the row shape, so a complete response schema is still unavailable. Do not infer fields from GenericObject."
}
OpenAPI metadata (incomplete):
{
"operationId": "reportManagedBusinessResourceCount",
"summary": "Record a managed product resource count",
"tags": [
"Management"
],
"security": [
{
"cliUserSessionBearerAuth": []
},
{
"makerTokenAccessBearerAuth": []
}
],
"x-farthershore-agent-operations": [
"resource_count.report"
],
"x-farthershore-agent-target": {
"kind": "path",
"targetKind": "business",
"parameter": "businessId"
},
"x-farthershore-agent-retry": [
{
"operationKey": "resource_count.report",
"kind": "convergent_write",
"keyRequired": false,
"enforcement": "resource_identity",
"responseSemantics": "point_in_time_write_result"
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
},
{
"name": "resource",
"in": "path",
"required": true,
"description": "Resource identifier",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"subscriptionId",
"count"
],
"properties": {
"subscriptionId": {
"type": "string",
"description": "Subscriber identifier"
},
"environmentId": {
"type": "string",
"nullable": true,
"description": "Environment id for preview environments, or null/omitted for production"
},
"count": {
"type": "integer",
"minimum": 0
},
"subjectType": {
"type": "string",
"maxLength": 64
},
"subjectId": {
"type": "string",
"maxLength": 160
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Recorded resource count",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
{
"browserBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Browser session token forwarded by the frontend"
},
"consumerBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Consumer portal session token forwarded by the frontend"
},
"cliUserSessionBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "cli_access JWT",
"description": "Short-lived CLI access JWT exchanged from a live user-bound fscli_ session. Eligibility is revalidated from current organization membership and role grants."
},
"makerTokenAccessBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "cli_access JWT",
"description": "Short-lived CLI access JWT exchanged from an organization-scoped mk_ MakerToken. Authority is limited to the token's frozen exact grants and business scope."
},
"rawCliCredentialBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "fscli_ session or mk_ MakerToken",
"description": "Raw CLI credential accepted only by exchange, organization discovery, and CLI-session revocation infrastructure."
},
"serviceJwtBearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Ed25519 service JWT",
"description": "Short-lived Farther Shore service identity JWT for internal machine calls"
},
"siteShellServiceJwt": {
"type": "apiKey",
"in": "header",
"name": "x-fs-service-jwt",
"description": "Short-lived Farther Shore site-shell service JWT with proxy:trust scope"
},
"localPreviewProxyLease": {
"type": "apiKey",
"in": "header",
"name": "x-fs-local-persona-proxy",
"description": "CLI-process-only local-preview lease (fslpl_…) attached by the `farthershore frontend dev|preview --live` loopback proxy together with `x-fs-local-preview-origin` (the exact http://localhost:<port> origin it was issued for). Verified against Core's lease store and pinned to one persona/environment/business/portal host; a raw header pair without a live lease grants nothing. Never sent by browser code."
},
"personaSessionCookie": {
"type": "apiKey",
"in": "cookie",
"name": "__Host-fs_persona_session",
"description": "Host-only HttpOnly persona session cookie. Accepted only through a trusted boundary: together with the hosted site shell's service JWT, or through the CLI's localhost preview proxy presenting a verified local-preview lease (x-fs-local-persona-proxy + x-fs-local-preview-origin). Never as a bearer."
}
}