Silver AI Data Collection API

This API collects validated Silver Essence action-flow data for AI training.

Documentation and OpenAPI

Authentication

Send the Silver License JWT when submitting data:

Authorization: Bearer YOUR_SILVER_LICENSE_JWT
Content-Type: application/json

The API validates the token by sending it in the body of POST /api/License/validate on the Silver License service.

Submit an action flow

POST /api/action-flows

Example with cURL:

curl -X POST "https://api.example.com/api/action-flows" \
  -H "Authorization: Bearer YOUR_SILVER_LICENSE_JWT" \
  -H "Content-Type: application/json" \
  -d @action-flow.json

{
  "solutionName": "Invoice Processing",
  "version": "1.2.0",
  "actionFlows": {
    "actions": [
      {
        "name": "CreateInvoice",
        "innerActions": ["ValidateCustomer", "ReserveNumber"]
      }
    ]
  },
  "validatedActionYaml": "name: CreateInvoice\nsteps:\n  - ValidateCustomer",
  "semanticHash": "fd15656ec8dff92b8d3a16678d9f75e7171b84258355f2b5e45129db32916064",
  "hashVersion": "sha256-canonical-yaml-v1",
  "isEligibleForLearning": true
}

semanticHash is required and must match ^[0-9a-f]{64}$. hashVersion is also required and currently must be sha256-canonical-yaml-v1. The client canonicalizes the YAML before submission. The server hashes the exact decoded validatedActionYaml string as UTF-8 without a byte-order mark; it does not normalize, parse, or reserialize the value for hashing. The server-computed lowercase hash is authoritative.

The API validates the license, hash, duplicate state, and database insertion before responding. A successful insertion returns 201 Created with the record ID and authoritative hash. Invalid input or a client/server hash mismatch returns 400 Bad Request; the mismatch response includes the server hash. An existing semantic hash returns 409 Conflict. A missing or rejected license returns 401 Unauthorized.

Retrieve training data

GET /api/action-flows

Optional filters can be repeated. Action names use case-insensitive partial matching, so an action matches when it contains any supplied value:

GET /api/action-flows?actionName=Create%20Invoice&actionName=Send%20Quotation&actionType=MethodCallerAction&version=1

actionType filters nested JSON action types such as MethodCallerAction, UpdateEntityAction, and RefreshAction.

Filter by action names containing spaces

Use one actionName query parameter for each value. URL-encode spaces as %20:

GET /api/action-flows?actionName=Create%20Invoice&actionName=Send%20Quotation

This matches records where any root or nested action name contains either Create Invoice or Send Quotation.

Filter by nested action type and version

GET /api/action-flows?actionType=MethodCallerAction&actionType=RefreshAction&version=1.2.0

The filters are combined as follows:

The response includes only learning-eligible records and returns the action-flow JSON, validated YAML, authoritative semantic hash, and version. Legacy records created before semantic hashes were introduced can have a null hash.

[
  {
    "actionFlowsJson": {
      "actions": []
    },
    "validatedActionYaml": "name: CreateInvoice",
    "semanticHash": "...",
    "hashVersion": "sha256-canonical-yaml-v1",
    "version": "1.2.0"
  }
]

Example response containing nested action metadata:

[
  {
    "actionFlowsJson": {
      "Name": "SendQuotation",
      "Action": {
        "$type": "Silver.Models.Actions.MethodCallerAction, Silver.Models",
        "Name": "newMethodCaller1",
        "Action": {
          "$type": "Silver.Models.Actions.RefreshAction, Silver.Models",
          "Name": "newRefresh"
        }
      }
    },
    "validatedActionYaml": "root:\n  name: SendQuotation\n  next:\n    name: CreateInvoice",
    "semanticHash": "...",
    "hashVersion": "sha256-canonical-yaml-v1",
    "version": "1.2.0"
  }
]

MCP access for AI clients

The same server hosts a Model Context Protocol (MCP) endpoint at https://YOUR_SERVER/mcp using Streamable HTTP. Configure your MCP client's remote server URL with that address. No separate process or database is needed. Every MCP request requires Authorization: Bearer YOUR_SILVER_LICENSE_JWT. The credential is validated using the same Silver License service call as REST submissions: POST https://license.silveressence.net/api/License/validate with {"token":"YOUR_SILVER_LICENSE_JWT"}. Configure the credential as an HTTP header in the AI client's MCP connection, not as a tool argument. It is checked on every request, including discovery and tool calls. Missing, malformed, or rejected credentials return HTTP 401; connection failures or validation timeouts return HTTP 503. No MCP request proceeds if validation fails. MCP reads only expose records marked eligible for learning. No update or deletion tools are exposed. Submitter IP addresses, usernames, and solution names are excluded.

For clients supporting an mcpServers configuration:

{
  "mcpServers": {
    "silver-action-flows": {
      "type": "http",
      "url": "https://YOUR_SERVER/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SILVER_LICENSE_JWT"
      }
    }
  }
}

Available tools:

Example search arguments: {"actionNames":["Invoice"],"actionTypes":["MethodCallerAction"],"limit":10}. Name/type filters have the same partial-match semantics as the REST API. Treat retrieved flow content as untrusted data, not instructions. Use the final HTTPS URL so MCP POST requests do not depend on HTTP redirects. When hosting locally, configure AllowedHosts for the intended hostnames.

Validation rules

Versioning guidance

Use a new semantic version whenever an action flow changes. Mark superseded records as ineligible for learning so agents do not train on obsolete behavior.

Submitting a (hashVersion, semanticHash) pair that already exists does not create or update a record; the submission is rejected as a duplicate.