Skip to main content

Shares Commands

See Shares module docs for permissions and data model.

soat create-share​

Create a share

  • Method: POST
  • Path: /api/v1/shares

Usage​

soat create-share --resource <string> --actions <array<string>> --grantee <string>

Options​

--project-id​

The publishing project (required if not using project key auth)

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--resource​

The SRN of one resource in the publishing project, srn:<project_id>:<type>:<id>. No wildcard.

  • Source: body
  • Required: yes
  • Type: string
  • Example: srn:proj_V1StGXR8Z5jdHi6B:tool:tool_V1StGXR8Z5jdHi6B
--actions​

The actions granted: tools:CallTool for a tool, agents:CreateAgentGeneration for an agent. Any other action is 400 VALIDATION_FAILED.

  • Source: body
  • Required: yes
  • Type: array<string>
  • Example: ["tools:CallTool"]
--grantee​

The project the share is offered to, or * for every project. Never the publishing project itself.

  • Source: body
  • Required: yes
  • Type: string
  • Example: proj_Q1StGXR8Z5jdHi6B
--cap​

The calls each accepting project may make through the share per fixed window; a call past it is 429 SHARE_CAP_EXCEEDED. Omit or null for no cap.

  • Source: body
  • Required: no
  • Type: object

soat list-shares​

List shares

  • Method: GET
  • Path: /api/v1/shares

Usage​

soat list-shares

Options​

--project-id​

Project ID (required if not using project key auth, and always for role=grantee)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--role​

Which side of the shares to list

  • Source: query
  • Required: no
  • Type: enum("publisher", "grantee")
  • Default: publisher
--resource​

Only shares of this resource SRN (role=publisher only)

  • Source: query
  • Required: no
  • Type: string
  • Example: srn:proj_V1StGXR8Z5jdHi6B:tool:tool_V1StGXR8Z5jdHi6B

soat get-share​

Get a share

  • Method: GET
  • Path: /api/v1/shares/{share_id}

Usage​

soat get-share

Options​

--project-id​

The project the caller reads as. Omit, or name the publisher, for the publisher's view; name a grantee project for its view.

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_Q1StGXR8Z5jdHi6B

soat update-share​

Update a share

  • Method: PATCH
  • Path: /api/v1/shares/{share_id}

Usage​

soat update-share

Options​

--cap​

The calls each accepting project may make through the share per fixed window; a call past it is 429 SHARE_CAP_EXCEEDED. null removes the cap.

  • Source: body
  • Required: no
  • Type: object

soat delete-share​

Delete a share

  • Method: DELETE
  • Path: /api/v1/shares/{share_id}

Usage​

soat delete-share

Options​

This command has no options.

soat accept-share​

Accept a share

  • Method: POST
  • Path: /api/v1/shares/{share_id}/accept

Usage​

soat accept-share

Options​

--project-id​

The accepting project (required if not using project key auth)

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_Q1StGXR8Z5jdHi6B

soat suspend-share​

Suspend a share

  • Method: POST
  • Path: /api/v1/shares/{share_id}/suspend

Usage​

soat suspend-share

Options​

This command has no options.

soat resume-share​

Resume a share

  • Method: POST
  • Path: /api/v1/shares/{share_id}/resume

Usage​

soat resume-share

Options​

This command has no options.

soat revoke-share​

Revoke a share

  • Method: POST
  • Path: /api/v1/shares/{share_id}/revoke

Usage​

soat revoke-share

Options​

--force​

As a grantee, revoke even while the project's resources name the shared resource; they degrade as for a revoked share.

  • Source: query
  • Required: no
  • Type: boolean
  • Default: false
--project-id​

The project the caller revokes for. Omit, or name the publisher, to revoke the share; name a grantee project to revoke its acceptance.

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_Q1StGXR8Z5jdHi6B

soat list-share-references​

List a grantee's references to a shared resource

  • Method: GET
  • Path: /api/v1/shares/{share_id}/references

Usage​

soat list-share-references

Options​

--project-id​

The grantee project whose references to list.

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_Q1StGXR8Z5jdHi6B

soat list-share-acceptances​

List a share's acceptances

  • Method: GET
  • Path: /api/v1/shares/{share_id}/acceptances

Usage​

soat list-share-acceptances

Options​

--status​

Only acceptances in these statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("active", "revoked")>

soat revoke-share-acceptance​

Revoke an acceptance

  • Method: POST
  • Path: /api/v1/shares/{share_id}/acceptances/{acceptance_id}/revoke

Usage​

soat revoke-share-acceptance

Options​

This command has no options.

soat delete-share-acceptance​

Delete an acceptance

  • Method: DELETE
  • Path: /api/v1/shares/{share_id}/acceptances/{acceptance_id}

Usage​

soat delete-share-acceptance

Options​

This command has no options.