Submit an Agent for Review — POST /v1/agent-submissions

Submit an A2A-compatible agent to the registry. Valid submissions are auto-approved by default. Returns the AgentSubmissionRecord with status.

Submits a new agent to the ServiceNet registry. The submission must include a valid A2A agent card, deployment configuration, a review profile, and a signed provider attestation.

By default, submissions that pass all validation checks (signature, schema, and review) are auto-approved and immediately published. Set SERVICENET_REQUIRE_ADMIN_APPROVE=1 on the node to require manual admin approval instead.

---

Submit an agent

POST /v1/agent-submissions

curl -X POST http://your-node:8042/v1/agent-submissions \
  -H 'content-type: application/json' \
  -d '{
    "provider_id": "acme-labs",
    "agent_id": "stripe-agent",
    "version": "0.1.0",
    "agent_card": {
      "name": "Stripe Agent",
      "description": "Handles Stripe payment flows",
      "url": "https://stripe-agent.example.com",
      "preferredTransport": "JSONRPC",
      "protocolVersion": "1.0",
      "supportsTask": false,
      "skills": [
        {
          "id": "payments.create_link",
          "name": "Create Payment Link",
          "description": "Creates a Stripe payment link"
        }
      ],
      "securitySchemes": { "oauth2": { "type": "oauth2" } },
      "security": [{ "oauth2": ["payments:write"] }]
    },
    "deployment": {
      "runtime": "remote_http",
      "endpoint": {
        "url": "https://stripe-agent.example.com/a2a",
        "protocol_binding": "JSONRPC",
        "protocol_version": "1.0"
      }
    },
    "review": {
      "risk_level": "medium",
      "data_classes": ["financial"],
      "destructive_actions": ["payments.refund"],
      "human_approval_required": true,
      "allowed_regions": ["AU", "US"]
    },
    "artifacts": {
      "documentation_url": "https://stripe-agent.example.com/docs",
      "security_url": "https://stripe-agent.example.com/security"
    },
    "attestations": {
      "attestation_signature": "<ATTESTATION_SIGNATURE>",
      "source_commit": "<COMMIT_SHA>",
      "build_digest": "<BUILD_DIGEST>"
    }
  }'

Body parameters

provider_id · string · required

The provider_id of the registered, active provider submitting this agent.

agent_id · string · required

Unique identifier for this agent (e.g. "stripe-agent"). Must be unique within the provider’s submissions.

version · string · required

Semantic version for this release (e.g. "0.1.0").

agent_card · object · required

A2A-compatible agent card object. Must include name, description, url, preferredTransport, protocolVersion, supportsTask, skills, securitySchemes, and security.

deployment · object · required

Deployment configuration.

Show deployment fields

runtime · string · required

Execution runtime identifier (e.g. "remote_http").

endpoint · object · required

Show endpoint fields

url · string · required

The publicly reachable A2A endpoint URL.

protocol_binding · string · required

Protocol binding (e.g. "JSONRPC").

protocol_version · string · required

Protocol version (e.g. "1.0").

interaction_protocol · string

Interaction protocol. Defaults to "google_a2a".

review · object · required

Review profile for this agent.

Show review fields

risk_level · string · required

One of "low", "medium", or "high".

data_classes · string[]

Categories of data handled (e.g. ["financial"]).

destructive_actions · string[]

List of destructive action identifiers.

human_approval_required · boolean

Whether invocations require human confirmation.

allowed_regions · string[]

ISO country codes where the agent may operate.

cost_per_call_units · integer

Cost in abstract units per invocation.

artifacts · object

Optional supporting artifact URLs.

Show artifacts fields

documentation_url · string

Link to the agent’s public documentation.

security_url · string

Link to the agent’s security disclosure page.

smoke_test_report_url · string

Link to an automated smoke test report for this version.

attestations · object · required

Provider attestation proving the submission’s integrity.

Show attestations fields

attestation_signature · string · required

Base64-encoded signature over the canonical attestation payload, which covers all submission fields including provider_id, agent_id, version, agent_card, deployment, review, artifacts, and all attestation metadata fields.

provider_attester_did · string

DID of the attesting party, if different from the provider DID.

delegation_token · string

Optional delegation token proving the attesting DID is authorised to sign on behalf of the provider.

source_commit · string

Git commit SHA of the source used for this build.

build_digest · string

Content digest of the build artifact (e.g. OCI image digest).

nonce · string

Unique nonce for this submission. Nodes may reject duplicate nonces from the same provider.

issued_at_ms · integer

Unix timestamp in milliseconds when the attestation was signed. Nodes may reject stale timestamps.

expires_at_ms · integer

Unix timestamp in milliseconds after which this submission must be rejected.

Response

Returns the created AgentSubmissionRecord with status 201 Created.

submission_id · string (UUID)

Unique identifier for this submission. Use it to query status or approve/reject via the admin API.

provider_id · string

The submitting provider’s identifier.

agent_id · string

The agent identifier.

version · string

The submitted version.

status · string

Submission lifecycle status. One of "draft", "submitted", "in_review", "approved", "rejected", "suspended", or "revoked". Auto-approved submissions will be "approved".

agent_card · object

The submitted A2A agent card.

deployment · object

The submitted deployment configuration.

review · AgentReviewProfile

The submitted review profile.

artifacts · AgentArtifacts

The submitted artifact URLs.

attestations · AgentAttestations

The submitted attestation data.

submitted_at · string

ISO 8601 timestamp of submission.

updated_at · string

ISO 8601 timestamp of the most recent status change.

reviewed_by · string

Reviewer identity. Set to "auto-approve" for automatically approved submissions.

review_notes · string

Optional reviewer notes.

rejection_reason · string

Reason for rejection. Present only when status is "rejected".

Status codes

Code	Meaning
201 Created	Submission accepted. Returns the AgentSubmissionRecord.
400 Bad Request	Missing required fields, invalid attestation signature, or schema validation failure.
403 Forbidden	The provider is revoked or blocked.

Example response

{
  "submission_id": "a1b2c3d4-0000-0000-0000-000000000001",
  "provider_id": "acme-labs",
  "agent_id": "stripe-agent",
  "version": "0.1.0",
  "status": "approved",
  "agent_card": { "name": "Stripe Agent", "..." : "..." },
  "deployment": {
    "runtime": "remote_http",
    "endpoint": {
      "url": "https://stripe-agent.example.com/a2a",
      "protocol_binding": "JSONRPC",
      "protocol_version": "1.0",
      "interaction_protocol": "google_a2a"
    }
  },
  "review": {
    "risk_level": "medium",
    "data_classes": ["financial"],
    "destructive_actions": ["payments.refund"],
    "human_approval_required": true,
    "allowed_regions": ["AU", "US"]
  },
  "artifacts": {
    "documentation_url": "https://stripe-agent.example.com/docs"
  },
  "attestations": {
    "attestation_signature": "<ATTESTATION_SIGNATURE>",
    "source_commit": "abc123"
  },
  "submitted_at": "2025-01-16T07:55:00Z",
  "updated_at": "2025-01-16T07:55:01Z",
  "reviewed_by": "auto-approve"
}

---

List submissions

GET /v1/agent-submissions

Retrieve submissions filtered by provider, agent, or status.

curl 'http://your-node:8042/v1/agent-submissions?provider_id=acme-labs&status=approved'

Query parameters

provider_id · string

Filter by provider identifier.

agent_id · string

Filter by agent identifier.

status · string

Filter by submission status. One of "draft", "submitted", "in_review", "approved", "rejected", "suspended", or "revoked".

Returns { "items": AgentSubmissionRecord[] }.

---

Get a single submission

GET /v1/agent-submissions/:submission_id

curl http://your-node:8042/v1/agent-submissions/a1b2c3d4-0000-0000-0000-000000000001

submission_id · string (UUID) · required

The submission_id returned when the submission was created.

Returns the full AgentSubmissionRecord or 404 Not Found if the submission does not exist.