Ctrlk
APIMCPOpen portal
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Sharing

Sharing adds existing members of the resource’s organization. Use POST /sharing/grantees for direct access, and organization invitations for new colleagues. Grant payloads keep editor (Developer) and viewer; membership roles use admin, developer and viewer. Grids accept viewer for use only. Only admins manage grid sharing; admins or creators manage project/app sharing. The older invitation endpoints handle existing invitations only.

Who a project, app or grid is shared with, and as what

get

Any API key can call this.

Also requires projects:admin (Delete projects and manage who they are shared with) when resourceType is project.

Also requires apps:admin (Delete or move apps and manage who they are shared with) when resourceType is app.

Also requires pools:admin (Delete grids and manage who they are shared with) when resourceType is grid.

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
resourceTypestring · enumRequired

What is shared

Possible values:
resourceIdstring · min: 1Required

Project or app id, or grid id

Responses
200

OK

application/json
get/sharing/grantees
GET /v1/sharing/grantees?resourceType=project&resourceId=text HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "resourceType": "project",
  "resourceId": "text",
  "resourceName": "text",
  "ownerEmail": null,
  "callerRole": "viewer",
  "grantees": [
    {
      "userId": "text",
      "email": null,
      "name": null,
      "role": "viewer",
      "orgRole": "admin",
      "grantedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Add members of the resource's organization to a project, app or grid. No invitation: access starts at once. Each role is at most theirs in the organization (a viewer is added as viewer; grids take viewer only), and someone already added gets the new role. People outside the organization can't be added

post

Any API key can call this.

Also requires projects:admin (Delete projects and manage who they are shared with) when resourceType is project.

Also requires apps:admin (Delete or move apps and manage who they are shared with) when resourceType is app.

Also requires pools:admin (Delete grids and manage who they are shared with) when resourceType is grid.

Errors specific to this operation:

  • 400 not_member: Someone named isn't in the resource's organization

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Body
resourceTypestring · enumRequired

What is shared

Possible values:
resourceIdstring · min: 1Required

Project or app id, or grid id

Responses
200

OK

application/json
post/sharing/grantees
POST /v1/sharing/grantees HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "resourceType": "project",
  "resourceId": "text",
  "people": [
    {
      "userId": "text",
      "role": "viewer"
    }
  ]
}
{
  "resourceType": "project",
  "resourceId": "text",
  "resourceName": "text",
  "ownerEmail": null,
  "callerRole": "viewer",
  "grantees": [
    {
      "userId": "text",
      "email": null,
      "name": null,
      "role": "viewer",
      "orgRole": "admin",
      "grantedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Change a grantee's role on a project or app (grids are shared as viewer only). On a grid, taking an old editor grant away also releases the machines and spot groups they added. Not on the caller's own grant.

patch

Any API key can call this.

Also requires projects:admin (Delete projects and manage who they are shared with) when resourceType is project.

Also requires apps:admin (Delete or move apps and manage who they are shared with) when resourceType is app.

Also requires pools:admin (Delete grids and manage who they are shared with) when resourceType is grid.

Errors specific to this operation:

  • 403 forbidden: The grant is the caller's own

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
granteeUserIdstringRequired

User id of the grantee, from the grantees list

Pattern: ^[0-9a-fA-F]{24}$
Body
resourceTypestring · enumRequired

What is shared

Possible values:
resourceIdstring · min: 1Required

Project or app id, or grid id

rolestring · enumRequired

Resource grant values: viewer reads; editor means Developer. Grids take viewer for use only; organization developers may deploy and viewers only read

Possible values:
Responses
200

OK

application/json
patch/sharing/grantees/{granteeUserId}
PATCH /v1/sharing/grantees/{granteeUserId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "resourceType": "project",
  "resourceId": "text",
  "role": "viewer"
}
{
  "resourceType": "project",
  "resourceId": "text",
  "resourceName": "text",
  "ownerEmail": null,
  "callerRole": "viewer",
  "grantees": [
    {
      "userId": "text",
      "email": null,
      "name": null,
      "role": "viewer",
      "orgRole": "admin",
      "grantedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "warning": null
}

Remove a grantee's access. On a grid, machines and spot groups a former co-manager added leave it too. Not on the caller's own grant (use leave).

delete

Any API key can call this.

Also requires projects:admin (Delete projects and manage who they are shared with) when resourceType is project.

Also requires apps:admin (Delete or move apps and manage who they are shared with) when resourceType is app.

Also requires pools:admin (Delete grids and manage who they are shared with) when resourceType is grid.

Errors specific to this operation:

  • 403 forbidden: The grant is the caller's own

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
granteeUserIdstringRequired

User id of the grantee, from the grantees list

Pattern: ^[0-9a-fA-F]{24}$
Query parameters
resourceTypestring · enumRequired

What is shared

Possible values:
resourceIdstring · min: 1Required

Project or app id, or grid id

Responses
200

OK

application/json
delete/sharing/grantees/{granteeUserId}
DELETE /v1/sharing/grantees/{granteeUserId}?resourceType=project&resourceId=text HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "warning": null
}

Give up the caller's own access to a shared project, app or grid. On a grid, their machines and spot groups leave with them.

post

Requires account:write (Accept or decline invitations, leave shared resources, manage notifications).

Errors specific to this operation:

  • 400 invalid_request: The caller owns the resource

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Body
resourceTypestring · enumRequired

What is shared

Possible values:
resourceIdstring · min: 1Required

Project or app id, or grid id

Responses
200

OK

application/json
post/sharing/leave
POST /v1/sharing/leave HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "resourceType": "project",
  "resourceId": "text"
}
{
  "warning": null
}

Invitations on a resource the caller manages, or those the caller sent. Pending and accepted ones: by resourceType and resourceId, or the sent ones within the credential's admin scopes and project restrictions

get

Any API key can call this.

Also requires projects:admin (Delete projects and manage who they are shared with) when resourceType is project.

Also requires apps:admin (Delete or move apps and manage who they are shared with) when resourceType is app.

Also requires pools:admin (Delete grids and manage who they are shared with) when resourceType is grid.

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Query parameters
resourceTypestring · enumOptional

What is shared

Possible values:
resourceIdstring · min: 1Optional

With resourceType: the resource whose invitations to list

Responses
200

OK

application/json
get/sharing/invitations
GET /v1/sharing/invitations HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "invitations": [
    {
      "id": "text",
      "resourceType": "project",
      "resourceId": "text",
      "resourceName": "text",
      "inviteeEmail": "text",
      "invitedByEmail": "text",
      "role": "viewer",
      "status": "pending",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "acceptedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Pending invitations addressed to the caller

get

Requires account:read (View invitations and notifications addressed to the user).

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Responses
200

OK

application/json
get/sharing/invitations/received
GET /v1/sharing/invitations/received HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "invitations": [
    {
      "id": "text",
      "resourceType": "project",
      "resourceId": "text",
      "resourceName": "text",
      "inviteeEmail": "text",
      "invitedByEmail": "text",
      "role": "viewer",
      "status": "pending",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "acceptedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Cancel an invitation the caller manages. Cancelling an accepted invitation revokes the access it granted. Needs the admin scope of the invitation's resource type.

delete

Any API key can call this.

Errors specific to this operation:

  • 403 forbidden: The grant is the caller's own

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
invitationIdstringRequired

Invitation id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
delete/sharing/invitations/{invitationId}
DELETE /v1/sharing/invitations/{invitationId} HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "warning": null
}

Accept an existing resource invitation addressed to the caller. For new team access, use organization invitations and add members to the resource

post

Requires account:write (Accept or decline invitations, leave shared resources, manage notifications).

Errors specific to this operation:

  • 409 no_org: A grid share, and the caller owns no organization to take it

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
invitationIdstringRequired

Invitation id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
post/sharing/invitations/{invitationId}/accept
POST /v1/sharing/invitations/{invitationId}/accept HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "resourceType": "project",
  "resourceId": "text",
  "resourceName": "text"
}

Decline an invitation addressed to the caller

post

Requires account:write (Accept or decline invitations, leave shared resources, manage notifications).

Authorizations
AuthorizationstringRequired

An API key from Account settings, e.g. kn_...

Path parameters
invitationIdstringRequired

Invitation id

Pattern: ^[0-9a-fA-F]{24}$
Responses
200

OK

application/json
post/sharing/invitations/{invitationId}/decline
POST /v1/sharing/invitations/{invitationId}/decline HTTP/1.1
Host: api.kinesis.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "declined": true
}
PreviousTemplates
NextGrids

Was this helpful?