Documentation Powered by ReDoc

Parcel (0.1.0)

Download OpenAPI specification:Download

Oasis Labs: feedback@oasislabs.com URL: https://oasislabs.com

Secure data sharing

Authentication

AccessToken

Security Scheme Type OAuth2
implicit OAuth Flow
Authorization URL: https://auth.oasislabs.com/oauth/authorize
Scopes:
  • parcel.public -

    Grants access to APIs that read only public data.

  • parcel.safe -

    Grants non-destructive access to APIs (e.g. create new resources like document uploads) and access to read private data when the token's actor (i.e. the app) can.

  • parcel.full -

    Grants access to APIs that read private data or write any data.

authorizationCode OAuth Flow
Authorization URL: https://auth.oasislabs.com/oauth/authorize
Token URL: https://auth.oasislabs.com/oauth/token
Refresh URL: https://auth.oasislabs.com/oauth/token
Scopes:
  • parcel.public -

    Grants access to APIs that read only public data.

  • parcel.safe -

    Grants non-destructive access to APIs (e.g. create new resources like document uploads) and access to read private data when the token's actor (i.e. the app) can.

  • parcel.full -

    Grants access to APIs that read private data or write any data.

clientCredentials OAuth Flow
Token URL: https://auth.oasislabs.com/oauth/token
Refresh URL: https://auth.oasislabs.com/oauth/token
Scopes:
  • parcel.public -

    Grants access to APIs that read only public data.

  • parcel.safe -

    Grants non-destructive access to APIs (e.g. create new resources like document uploads) and access to read private data when the token's actor (i.e. the app) can.

  • parcel.full -

    Grants access to APIs that read private data or write any data.

identity

Operations on your Parcel identity

Create a new identity.

Authorizations:
AccessToken (parcel.safe)
Request Body schema: application/json
required
Array of objects (IdentityTokenVerifier)

Responses

Request samples

Content type
application/json
{
  • "tokenVerifiers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Return the identity of the authorized requester.

Authorizations:
AccessToken (parcel.public)

Responses

Response samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Return the specified identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

Responses

Response samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Update the requested identity.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

Request Body schema: application/json

The identity's new fields.

required
Array of objects (IdentityTokenVerifier)

Responses

Request samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Delete the specified identity. An identity can only be deleted by itself.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return linked Ethereum addresses.

Authorizations:
AccessToken (parcel.safe)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Link a new Ethereum address.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

Request Body schema: application/json

Proof of ownership of the Ethereum account.

proof
required
string <hex>

An hex-encoded signature of the string parcel identity = <your identity id>, made using web3_personalSign.

Responses

Request samples

Content type
application/json
{
  • "proof": "0x0b712114734b34fc51a16d32e22f428a28caffdf0c608e42ff16bed204a6b728666077fc966147f4e533e68452341da2e6d064f1a9410456d35476759d0f62f61b"
}

Response samples

Content type
application/json
{
  • "address": "0x16355dda54b8421f8e173d12b96371a36f76d633"
}

Unlink the specified Ethereum address.

Authorizations:
AccessToken (parcel.full)
path Parameters
identityId
required
string (IdentityId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of the identity.

ethereumAddress
required
string <hex>
Example: 0x16355dda54b8421f8e173d12b96371a36f76d633

An Ethereum address representing a linked identity.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the permissions granted by this identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return the token balances held by the identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return the token balance held by the identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "token": "TVehZvHzZ2ADnjZx1qoLrTq",
  • "balance": 0
}

Initiate a token transfer.

An alias for POST /tokens/{tokenId}/transfers.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

Request Body schema: application/json
required
Array of objects (IdentityTokenVerifier)

Responses

Request samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Grant permission.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "grants": [
    ]
}

Query whether the identity has accepted the permission.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ],
  • "id": "P7kGbYvko5CSM6ixzpVUKnH",
  • "appId": "APXf29TgTSMFeHGXY627vi5"
}

Revoke the specified permission.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

documents

Operations on documents

Upload a new document.

Accepts a new document, encrypting the data with a secure random key.

This endpoint will redirect to https://storage.oasislabs.com/v1/parcel. If your HTTP client does not resend the Authorization header on redirect (many don't), you must upload to the storage URL directly!

Authorizations:
AccessToken (parcel.safe)
Request Body schema: multipart/form-data
required
object (DocumentCreateOrUpdateParams)
data
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "id": "DSgUhs1oiQ8vr5pQH8pgfgs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "size": 1024,
  • "dataUrl": "parcel://storage/ea2216c1-dd52-4f6e-aa39-f75d39e20bdc",
  • "details": {
    }
}

Search documents.

Return public information about documents that match the (optional) search parameters.

Authorizations:
AccessToken (parcel.public)
query Parameters
object

Controls the number of results returned and after what offset

Request Body schema: application/json
selectedByCondition
object

Search for documents that would be selected if a grant with the specified condition were created. Use this field for simulating a grant.

If accessibleInContext is also specified, this field selects documents both accessible in the context and selected by the condition (i.e. existing conditions apply).

object

Search for documents that can be accessed in the provided context. This field allows you to discover documents that you can access either yourself, or from a job.

Responses

Request samples

Content type
application/json
{
  • "selectedByCondition": {
    },
  • "accessibleInContext": {
    }
}

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return an existing document.

Authorizations:
AccessToken (parcel.public)
path Parameters
documentId
required
string (DocumentId)
Example: DSgUhs1oiQ8vr5pQH8pgfgs

The unique identifier of the document.

Responses

Response samples

Content type
application/json
{
  • "id": "DSgUhs1oiQ8vr5pQH8pgfgs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "size": 1024,
  • "dataUrl": "parcel://storage/ea2216c1-dd52-4f6e-aa39-f75d39e20bdc",
  • "details": {
    }
}

Update an existing document.

Authorizations:
AccessToken (parcel.full)
path Parameters
documentId
required
string (DocumentId)
Example: DSgUhs1oiQ8vr5pQH8pgfgs

The unique identifier of the document.

Request Body schema: application/json

The document's new fields.

required
IdentityId (string) or AppId (string) or EscrowAccount (string)

Upload the document and set the initial owner to either the specified identity or the tokenization escrow identity in your name.

required
object

A dictionary of user-provided document details. Any fields not defined by in this API are not used by Parcel and contain arbitrary application-specific data.

Responses

Request samples

Content type
application/json
{
  • "id": "DSgUhs1oiQ8vr5pQH8pgfgs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "size": 1024,
  • "dataUrl": "parcel://storage/ea2216c1-dd52-4f6e-aa39-f75d39e20bdc",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "id": "DSgUhs1oiQ8vr5pQH8pgfgs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "size": 1024,
  • "dataUrl": "parcel://storage/ea2216c1-dd52-4f6e-aa39-f75d39e20bdc",
  • "details": {
    }
}

Delete the document.

Authorizations:
AccessToken (parcel.full)
path Parameters
documentId
required
string (DocumentId)
Example: DSgUhs1oiQ8vr5pQH8pgfgs

The unique identifier of the document.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Downloads decrypted document data.

Decrypts and downloads a document that you have been granted.

This endpoint will redirect to https://storage.oasislabs.com/v1/parcel/{documentId}/download. If your HTTP client does not resend the Authorization header on redirect (many don't), you must upload to the storage URL directly!

Authorizations:
AccessToken (parcel.safe)
path Parameters
documentId
required
string (DocumentId)
Example: DSgUhs1oiQ8vr5pQH8pgfgs

The unique identifier of the document.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Retrieves document history.

Return the access events for an existing document.

Authorizations:
AccessToken (parcel.public)
path Parameters
documentId
required
string (DocumentId)
Example: DSgUhs1oiQ8vr5pQH8pgfgs

The unique identifier of the document.

query Parameters
object

The filter to apply, if any. Set fields are ANDed together.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

databases

Operations on databases

Create a new database.

Authorizations:
AccessToken (parcel.public)
Request Body schema: application/json
name
required
string

The name of the database.

Responses

Request samples

Content type
application/json
{
  • "name": "My Database"
}

Response samples

Content type
application/json
{
  • "id": "SW7PKHxK7FUFkpwxwW7HLf5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "name": "My Database"
}

listDatabases

Authorizations:
AccessToken (parcel.public)
query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Returns an existing database.

All fields are public.

Authorizations:
AccessToken (parcel.public)
path Parameters
databaseId
required
string (DatabaseId)
Example: SW7PKHxK7FUFkpwxwW7HLf5

The unique identifier of the database.

Responses

Response samples

Content type
application/json
{
  • "id": "SW7PKHxK7FUFkpwxwW7HLf5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "name": "My Database"
}

Update an existing database.

Authorizations:
AccessToken (parcel.full)
path Parameters
databaseId
required
string (DatabaseId)
Example: SW7PKHxK7FUFkpwxwW7HLf5

The unique identifier of the database.

Request Body schema: application/json
name
required
string

The name of the database.

id
required
string (DatabaseId)

Database unique identifier

owner
required
string (IdentityId)

Identity unique identifier

Responses

Request samples

Content type
application/json
{
  • "id": "SW7PKHxK7FUFkpwxwW7HLf5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "name": "My Database"
}

Response samples

Content type
application/json
{
  • "id": "SW7PKHxK7FUFkpwxwW7HLf5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "creator": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "name": "My Database"
}

Query an existing database.

Authorizations:
AccessToken (parcel.safe)
path Parameters
databaseId
required
string (DatabaseId)
Example: SW7PKHxK7FUFkpwxwW7HLf5

The unique identifier of the database.

Request Body schema: application/json
sql
required
string <sql>
param
object

Responses

Request samples

Content type
application/json
{
  • "sql": "CREATE TABLE threat_intels (wallet TEXT, inner TEXT, instance INTEGER, data JSON)",
  • "params": { }
}

Response samples

Content type
application/json
[
  • { }
]

Deletes an existing database.

Authorizations:
AccessToken (parcel.full)
path Parameters
databaseId
required
string (DatabaseId)
Example: SW7PKHxK7FUFkpwxwW7HLf5

The unique identifier of the database.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Append rows of data to an existing database.

Authorizations:
AccessToken (parcel.safe)
path Parameters
databaseId
required
string (DatabaseId)
Example: SW7PKHxK7FUFkpwxwW7HLf5

The unique identifier of the database.

Request Body schema: application/json
tableName
required
string
rows
required
array

Responses

Request samples

Content type
application/json
{
  • "tableName": "threat_intels",
  • "rows": [
    ]
}

Response samples

Content type
application/json
[
  • { }
]

apps

Authorize and manage apps and their permissions

List apps.

Authorizations:
AccessToken (parcel.public)
query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Create a new app.

Authorizations:
AccessToken (parcel.public)
Request Body schema: application/json
acceptanceText
required
string

The text shown to the user after accepting the app's invitation but before being returned to the organization's website.

allowUserUploads
required
boolean

Whether to allow users to directly contribute documents to this app.

brandingColor
required
string <RGB hex>

The organizations primary brand color that will be used when rendering the app invitation, etc.

category
required
string

A tag describing the app's category (e.g., health, finance)

extendedDescription
required
string

An extended description of the app.

homepageUrl
required
string <url>

A URL pointing to the app publisher's homepage.

invitationText
required
string

The text shown to the user when viewing this app's invitation.

inviteOnly
required
boolean

Whether this app can be joined by anyone, or a select set of identities. If participation is invite-only, the condition and grants of the app are only accessible to invitees.

invites
required
Array of strings (IdentityId)

The set of identities that are permitted to join this app.

logoUrl
required
string <url>

A URL pointing to the app's logo.

name
required
string

The name of the app.

organization
required
string

The name of the app publisher's organization.

privacyPolicy
required
string <url>

A link to the text presented to the user when viewing the app's privacy policy.

rejectionText
required
string

The text shown to the user after rejecting the app's invitation.

shortDescription
required
string

The short description of this app seen by users when shown the app's summary.

termsAndConditions
required
string <url>

A link to the text presented to the user when viewing the app's Terms & Conditions.

required
object (IdentityCreateParams)

Responses

Request samples

Content type
application/json
{
  • "acceptanceText": "Cool, let's get started!",
  • "admins": [
    ],
  • "allowUserUploads": true,
  • "brandingColor": "#ff3f0f",
  • "category": "example apps",
  • "collaborators": [
    ],
  • "extendedDescription": "Provides the most superlative reciprocal agreements pertaining to the use of\ncollections of information.\n",
  • "homepageUrl": "https://example.com",
  • "invitationText": "Hello, please use our app.",
  • "inviteOnly": false,
  • "invites": [ ],
  • "logoUrl": "https://example.com/logo.png",
  • "name": "App!",
  • "organization": "Example App",
  • "privacyPolicy": "We will never misuse your data. In fact, we can't even access it!",
  • "published": false,
  • "rejectionText": "Okay, maybe some other time then.",
  • "shortDescription": "High quality data sharing.",
  • "termsAndConditions": "We won't do anything bad and neither will you.",
  • "identity": {
    }
}

Response samples

Content type
application/json
{
  • "acceptanceText": "Cool, let's get started!",
  • "admins": [
    ],
  • "allowUserUploads": true,
  • "brandingColor": "#ff3f0f",
  • "category": "example apps",
  • "collaborators": [
    ],
  • "extendedDescription": "Provides the most superlative reciprocal agreements pertaining to the use of\ncollections of information.\n",
  • "homepageUrl": "https://example.com",
  • "invitationText": "Hello, please use our app.",
  • "inviteOnly": false,
  • "invites": [ ],
  • "logoUrl": "https://example.com/logo.png",
  • "name": "App!",
  • "organization": "Example App",
  • "privacyPolicy": "We will never misuse your data. In fact, we can't even access it!",
  • "published": false,
  • "rejectionText": "Okay, maybe some other time then.",
  • "shortDescription": "High quality data sharing.",
  • "termsAndConditions": "We won't do anything bad and neither will you.",
  • "id": "APXf29TgTSMFeHGXY627vi5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs"
}

Return an existing app.

The owner will receive private and shared fields. Invitees will only receive shared fields.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Responses

Response samples

Content type
application/json
{
  • "acceptanceText": "Cool, let's get started!",
  • "admins": [
    ],
  • "allowUserUploads": true,
  • "brandingColor": "#ff3f0f",
  • "category": "example apps",
  • "collaborators": [
    ],
  • "extendedDescription": "Provides the most superlative reciprocal agreements pertaining to the use of\ncollections of information.\n",
  • "homepageUrl": "https://example.com",
  • "invitationText": "Hello, please use our app.",
  • "inviteOnly": false,
  • "invites": [ ],
  • "logoUrl": "https://example.com/logo.png",
  • "name": "App!",
  • "organization": "Example App",
  • "privacyPolicy": "We will never misuse your data. In fact, we can't even access it!",
  • "published": false,
  • "rejectionText": "Okay, maybe some other time then.",
  • "shortDescription": "High quality data sharing.",
  • "termsAndConditions": "We won't do anything bad and neither will you.",
  • "id": "APXf29TgTSMFeHGXY627vi5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs"
}

Update an existing app.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Request Body schema: application/json

The app's new fields.

acceptanceText
required
string

The text shown to the user after accepting the app's invitation but before being returned to the organization's website.

allowUserUploads
required
boolean

Whether to allow users to directly contribute documents to this app.

brandingColor
required
string <RGB hex>

The organizations primary brand color that will be used when rendering the app invitation, etc.

category
required
string

A tag describing the app's category (e.g., health, finance)

extendedDescription
required
string

An extended description of the app.

homepageUrl
required
string <url>

A URL pointing to the app publisher's homepage.

invitationText
required
string

The text shown to the user when viewing this app's invitation.

inviteOnly
required
boolean

Whether this app can be joined by anyone, or a select set of identities. If participation is invite-only, the condition and grants of the app are only accessible to invitees.

invites
required
Array of strings

The set of identities that are permitted to join this app.

logoUrl
required
string <url>

A URL pointing to the app's logo.

name
required
string

The name of the app.

organization
required
string

The name of the app publisher's organization.

privacyPolicy
required
string <url>

A link to the text presented to the user when viewing the app's privacy policy.

rejectionText
required
string

The text shown to the user after rejecting the app's invitation.

shortDescription
required
string

The short description of this app seen by users when shown the app's summary.

termsAndConditions
required
string <url>

A link to the text presented to the user when viewing the app's Terms & Conditions.

owner
required
string (IdentityId)

Identity unique identifier

admins
required
Array of strings (IdentityId)
collaborators
required
Array of strings (IdentityId)
published
required
boolean

Whether this app has been published and is able to be joined. Once an app is published, it cannot be unpublished.

Responses

Request samples

Content type
application/json
{
  • "acceptanceText": "Cool, let's get started!",
  • "admins": [
    ],
  • "allowUserUploads": true,
  • "brandingColor": "#ff3f0f",
  • "category": "example apps",
  • "collaborators": [
    ],
  • "extendedDescription": "Provides the most superlative reciprocal agreements pertaining to the use of\ncollections of information.\n",
  • "homepageUrl": "https://example.com",
  • "invitationText": "Hello, please use our app.",
  • "inviteOnly": false,
  • "invites": [ ],
  • "logoUrl": "https://example.com/logo.png",
  • "name": "App!",
  • "organization": "Example App",
  • "privacyPolicy": "We will never misuse your data. In fact, we can't even access it!",
  • "published": false,
  • "rejectionText": "Okay, maybe some other time then.",
  • "shortDescription": "High quality data sharing.",
  • "termsAndConditions": "We won't do anything bad and neither will you.",
  • "id": "APXf29TgTSMFeHGXY627vi5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs"
}

Response samples

Content type
application/json
{
  • "acceptanceText": "Cool, let's get started!",
  • "admins": [
    ],
  • "allowUserUploads": true,
  • "brandingColor": "#ff3f0f",
  • "category": "example apps",
  • "collaborators": [
    ],
  • "extendedDescription": "Provides the most superlative reciprocal agreements pertaining to the use of\ncollections of information.\n",
  • "homepageUrl": "https://example.com",
  • "invitationText": "Hello, please use our app.",
  • "inviteOnly": false,
  • "invites": [ ],
  • "logoUrl": "https://example.com/logo.png",
  • "name": "App!",
  • "organization": "Example App",
  • "privacyPolicy": "We will never misuse your data. In fact, we can't even access it!",
  • "published": false,
  • "rejectionText": "Okay, maybe some other time then.",
  • "shortDescription": "High quality data sharing.",
  • "termsAndConditions": "We won't do anything bad and neither will you.",
  • "id": "APXf29TgTSMFeHGXY627vi5",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "owner": "IPoxXkdvFsrqzDdU7h3QqSs"
}

Delete the app.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the app's identity.

A convenience method for getting the app's identity. In fact, it's possible to call the /identities/{id} endpoint with the app's own app ID since app IDs are also identity Ids.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Responses

Response samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Update the app's identity.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Request Body schema: application/json

The app identity's new fields.

required
Array of objects (IdentityTokenVerifier)

Responses

Request samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

List clients.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": []
}

Create a new client.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Request Body schema: application/json
One of
type
required
string
Value: "frontend"
redirectUris
required
Array of strings <url>

The client's set of allowed redirect URIs.

postLogoutRedirectUris
required
Array of strings <url>

The client's set of allowed post-logout redirect URIs.

name
required
string

The name of this client.

Responses

Request samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Return an existing client.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Responses

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Update an existing client.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Request Body schema: application/json

The update to apply.

One of
type
required
string
Value: "frontend"
redirectUris
required
Array of strings <url>

The client's set of allowed redirect URIs.

postLogoutRedirectUris
required
Array of strings <url>

The client's set of allowed post-logout redirect URIs.

name
required
string

The name of this client.

Responses

Request samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Delete the client.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the requested app client.

Authorizations:
AccessToken (parcel.public)
path Parameters
clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Responses

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Return the permissions associated with this app.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new permission. Requires that the app not yet be published.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Request Body schema: application/json
required
Array of objects (GrantSpec)
name
required
string

The name of this permission.

description
required
string

The description of this permission seen by users when shown in an app.

allowText
required
string

Text seen by users when accepting this permission.

denyText
required
string

Text seen by users when denying this permission.

Responses

Request samples

Content type
application/json
{
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ],
  • "id": "P7kGbYvko5CSM6ixzpVUKnH",
  • "appId": "APXf29TgTSMFeHGXY627vi5"
}

Return an existing permission.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ],
  • "id": "P7kGbYvko5CSM6ixzpVUKnH",
  • "appId": "APXf29TgTSMFeHGXY627vi5"
}

Delete the permission.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

clients

Authorize and manage apps' clients

List clients.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": []
}

Create a new client.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Request Body schema: application/json
One of
type
required
string
Value: "frontend"
redirectUris
required
Array of strings <url>

The client's set of allowed redirect URIs.

postLogoutRedirectUris
required
Array of strings <url>

The client's set of allowed post-logout redirect URIs.

name
required
string

The name of this client.

Responses

Request samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Return an existing client.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Responses

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Update an existing client.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Request Body schema: application/json

The update to apply.

One of
type
required
string
Value: "frontend"
redirectUris
required
Array of strings <url>

The client's set of allowed redirect URIs.

postLogoutRedirectUris
required
Array of strings <url>

The client's set of allowed post-logout redirect URIs.

name
required
string

The name of this client.

Responses

Request samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Response samples

Content type
application/json
Example
FrontendClientConfig
FrontendClientConfig
BackendClientConfig
ServiceClientConfig
{}

Delete the client.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

clientId
required
string (ClientId)
Example: C63oxRsDuqf9RTW36cDXRxz

The unique identifier of the client.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

permissions

Manage permissions and the granting thereof

Return the permissions granted by this identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Grant permission.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "grants": [
    ]
}

Query whether the identity has accepted the permission.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ],
  • "id": "P7kGbYvko5CSM6ixzpVUKnH",
  • "appId": "APXf29TgTSMFeHGXY627vi5"
}

Revoke the specified permission.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the permissions associated with this app.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new permission. Requires that the app not yet be published.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

Request Body schema: application/json
required
Array of objects (GrantSpec)
name
required
string

The name of this permission.

description
required
string

The description of this permission seen by users when shown in an app.

allowText
required
string

Text seen by users when accepting this permission.

denyText
required
string

Text seen by users when denying this permission.

Responses

Request samples

Content type
application/json
{
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ],
  • "id": "P7kGbYvko5CSM6ixzpVUKnH",
  • "appId": "APXf29TgTSMFeHGXY627vi5"
}

Return an existing permission.

Authorizations:
AccessToken (parcel.public)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "Permission for Example App",
  • "description": "Permission for Example App to use personal data of participants.",
  • "allowText": "I allow Example App to use all of my data. Example App will have full functionality.",
  • "denyText": "I disallow Example App from using data. Example App will have limited functionality.",
  • "grants": [
    ],
  • "id": "P7kGbYvko5CSM6ixzpVUKnH",
  • "appId": "APXf29TgTSMFeHGXY627vi5"
}

Delete the permission.

Authorizations:
AccessToken (parcel.full)
path Parameters
appId
required
string (AppId)
Example: APXf29TgTSMFeHGXY627vi5

The unique identifier of the app.

permissionId
required
string (PermissionId)
Example: P7kGbYvko5CSM6ixzpVUKnH

The unique identifier of the permission.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

grants

One-off document access authorization

Create a new grant.

Authorizations:
AccessToken (parcel.full)
Request Body schema: application/json
(IdentityOrAppId (IdentityId (string) or AppId (string))) or string

The ID of the identity to which the grant is made or everyone to make the grant to everyone.

condition
object (Condition)

Grant condition, in the grant condition DSL. Some selectors are flagged as EXPERIMENTAL. Please feel free to report bugs with these features and/or request new ones via our feedback form.

Condition DSL

Selectors

  • { "identity.id": RelationalOp } - The Parcel ID of the identity requesting access.

  • { "document.id": RelationalOp } - The Parcel ID of the requested document.

  • { "document.creator": RelationalOp } - The Parcel ID of the requested document's creator.

  • { "document.owner": RelationalOp } - The Parcel ID of the requested document's owner.

  • { "document.title": RelationalOp } - The title of the requested document.

  • { "document.tags": SetOp } - The annotated tags on the requested document.

  • { "document.originatingJob": RelationalOp } - The ID of the job that created this document, if any.

  • { "database.id": RelationalOp } - The Parcel ID of the requested database.

  • { "database.creator": RelationalOp } - The Parcel ID of the requested database's creator.

  • { "database.owner": RelationalOp } - The Parcel ID of the requested database's owner.

  • { "database.name": RelationalOp } - The name of the requested database.

  • { "job.spec.image": RelationalOp } - EXPERIMENTAL. The job image that will use the requested document. This is a Docker digest, e.g. sha256:a75aba1e60615dcced909b2a02f24dcc3a0eacf6da7758c8dc5d9e970cb5cf60

  • { "job.spec.inputs": ArrayOp } - EXPERIMENTAL. The input document filepaths for the requested job.

  • { "job.spec.outputs": ArrayOp } - EXPERIMENTAL. The output document filepaths for the requested job.

  • { "accessTime": RelationalOp } - The ISO 8601 time of document access.

  • { "worker.id": RelationalOp } - EXPERIMENTAL. The Parcel ID of the worker executing the requested job.

  • { "worker.version": RelationalOp } - EXPERIMENTAL. The version of the worker executing the requested job.

Logical Operators (LogicalOp)

  • { "$and": [LogicalOp | Selector] } - Checks if all expressions in the (right-hand side) RHS array match.
  • { "$or": [LogicalOp | Selector] } - Checks if any expression in the RHS array matches.
  • { "$or": [LogicalOp | Selector] } - Checks if all expressions in the RHS array do not match.
  • { "$not": LogicalOp | Selector } - Returns the inverse of the RHS.

Relational Operators (RelationalOp)

For operators with literal parameters, the literal must have the same type as the selector.

  • { "$eq": Primitive } - Checks if the specified selector is equal to the provided value.

  • { "$ne": Primitive } - Checks if the specified selector is not equal to the provided value.

  • { "$gte": Comparable } - Checks if the compared selector is greater than or equal to the provided value.

  • { "$gt": Comparable } - Checks if the compared selector is less than the provided value.

  • { "$lte": Comparable } - Checks if the compared selector is less than or equal to the provided value.

  • { "$lt": Comparable } - Checks if the compared selector is greater than the provided value.

  • { "$in": Primitive[] } - Checks if the compared selector is a member of the provided set.

  • { "$nin": Primitive[] } - Checks if the compared selector is not a member of the provided set.

Array Operators (ArrayOp)

  • { "$any": RelationalOp } - matches if any element of the selected array matches
  • { "$all": RelationalOp } - matches if all elements of the selected array match
  • { "$size": RelationalOp } - matches if the length of the selected array matches

Set Operators (SetOp)

  • { "$contains": Primitive } - matches if the selected set contains the element
  • { "$intersects": Primitive[] }
    • matches if the selected set intersects the provided set
  • { "$superset": Primitive[] }
    • matches if the selected set contains at least all of the elements in the provided set
  • { "$subset": Primitive[] }
    • matches if the selected set contains only elements from the provided set
  • { "$values": ArrayOp }
    • recursively matches using the array operator on the set values
  • { "$size": RelationalOp } - matches if the length of the selected set matches
capabilities
string (Capabilities)
Default: "read"

The capabilities that are afforded to the grantee. Capabilities are comparable to AccessToken scopes, but are tailored to delegation rather than impersonation.

Capabilities are specified as space-separated identifiers chosen from the following:

  • read - The ability to read the document.
  • delegate - The ability to delegate this grant to others. The delegated grant's condition may be any subset of the original's.
delegating
string

The grant to extend by delegation. If the specified grant is delegable, with you as the grantee, and not already delegated, this grant will be created by you on behalf of the original granter.

The grantee of the new grant will be able to access the granter's documents until any delegated grant in the chain is revoked.

More specifically, the granter of this grant will be the same as the delegated grant, and the condition will be the union of the new grant's condition and the delegated grant's condition.

Responses

Request samples

Content type
application/json
{
  • "grantee": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "condition": {
    },
  • "capabilities": "read delegate",
  • "delegating": "GSjAcmpmKPTfeCxrfbs4kSe"
}

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "grantee": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "condition": {
    },
  • "capabilities": "read delegate",
  • "delegating": "undefined",
  • "id": "GSjAcmpmKPTfeCxrfbs4kSe",
  • "granter": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "permission": "P7kGbYvko5CSM6ixzpVUKnH"
}

Return the grants based on the granter or grantee.

Return grants that match the (optional) filter.

Authorizations:
AccessToken (parcel.public)
query Parameters
object

The filter to apply, if any. Set fields are ANDed together.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return an existing grant.

Authorizations:
AccessToken (parcel.public)
path Parameters
grantId
required
string (GrantId)
Example: GSjAcmpmKPTfeCxrfbs4kSe

The unique identifier of the grant.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "grantee": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "condition": {
    },
  • "capabilities": "read delegate",
  • "delegating": "undefined",
  • "id": "GSjAcmpmKPTfeCxrfbs4kSe",
  • "granter": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "permission": "P7kGbYvko5CSM6ixzpVUKnH"
}

Delete the grant.

Authorizations:
AccessToken (parcel.full)
path Parameters
grantId
required
string (GrantId)
Example: GSjAcmpmKPTfeCxrfbs4kSe

The unique identifier of the grant.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

compute

Off-chain computation - operations for end users

Enqueue a new job.

Authorizations:
AccessToken (parcel.safe)
Request Body schema: application/json

The job to equeue.

name
required
string

A human-readable name for the job. Intended to help with monitoring and debugging. The name SHOULD be unique among jobs submitted by the same user.

cmd
required
Array of strings

The command-line arguments to the command that should be run to start the job. This corresponds to CMD in Docker terminology; note that images running on Parcel are required to have a non-empty ENTRYPOINT, so the actual command that runs will be the concatenation of ENTRYPOINT and this field.

image
required
string

The name of the docker image to use, optionally prefixed with an image repository hostname. See docker pull documentation for a full description of allowable formats.

object

Environment variables to use when running the image. Setting PATH is not allowed.

object

The set of rules that define how a job is allowed to communicate with various network entities. All network traffic that is not explicitly whitelisted here will be blocked.

Array of objects
Array of objects
cpus
number

The (fractional) number of cpus requested to run the job. This is clamped by a per-worker maximum. 0 will default to the worker-allowed maximum.

memory
string

The amount of memory requested to run the job. This is clamped by a per-worker maximum. Format: []. Number is a positive integer. Unit can be one of M or G. Minimum is 4M. 0 will default to the worker-allowed maximum.

Responses

Request samples

Content type
application/json
{
  • "name": "CreditScorePrediction.p30.filtered",
  • "cmd": [
    ],
  • "image": "tensorflow:2.3.0",
  • "env": {
    },
  • "networkPolicy": {
    },
  • "inputDocuments": [
    ],
  • "outputDocuments": [
    ],
  • "cpus": 0.5,
  • "memory": "2G"
}

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "id": "J8dqyKxRYXZSqZyFjcM8Suz",
  • "spec": {
    },
  • "io": {
    },
  • "status": {
    }
}

List known jobs.

Return all known jobs visible to the current user and matching the (optional) filter. Includes completed, pending, and in-progress jobs.

Authorizations:
AccessToken (parcel.public)
query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return information about a known job.

Authorizations:
AccessToken (parcel.public)
path Parameters
jobId
required
string (JobId)
Example: J8dqyKxRYXZSqZyFjcM8Suz

The unique identifier of the job.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "id": "J8dqyKxRYXZSqZyFjcM8Suz",
  • "spec": {
    },
  • "io": {
    },
  • "status": {
    }
}

Terminate a currently running job.

Authorizations:
AccessToken (parcel.safe)
path Parameters
jobId
required
string (JobId)
Example: J8dqyKxRYXZSqZyFjcM8Suz

The unique identifier of the job.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the status about a known job.

In contrast to the more full-fledged /compute/jobs/{job_id} endpoint, this endpoint

  • Does not fetch the private spec from the chain, so it can return faster.
  • Returns 404 if the status of the job is no longer tracked, even if other job info is registered on the chain and known. Both of those properties make this endpoint particularly suitable for polling for job completion.
Authorizations:
AccessToken (parcel.public)
path Parameters
jobId
required
string (JobId)
Example: J8dqyKxRYXZSqZyFjcM8Suz

The unique identifier of the job.

Responses

Response samples

Content type
application/json
{
  • "id": "J8dqyKxRYXZSqZyFjcM8Suz",
  • "status": {
    }
}

meter

Usage monitoring and quotas for Parcel API usage

Get a metering report for your API usage

Authorizations:
AccessToken (parcel.public)
query Parameters
object

The filter to apply, if any. Set fields are ANDed together.

Responses

Response samples

Content type
application/json
{
  • "createCount": 0,
  • "readCount": 0,
  • "writeCount": 0,
  • "deleteCount": 0,
  • "uploadCount": 0,
  • "downloadCount": 0,
  • "uploadSizeBytes": 0,
  • "downloadSizeBytes": 0,
  • "computeMsec": 0,
  • "computeCpuMsec": 0,
  • "computeMemoryMsec": 0
}

Get your monthly API usage quota limits

Authorizations:
AccessToken (parcel.public)

Responses

Response samples

Content type
application/json
{
  • "apiCallsLimit": 0,
  • "accessedBytesLimit": 0,
  • "computeMsecLimit": 0
}

Update your monthly API usage quota limits

Authorizations:
AccessToken (parcel.public)
Request Body schema: application/json

The new quota for this month, and all subsequent months until changed.

apiCallsLimit
number

The monthly limit on your number of Parcel API calls made. By default this is set to 10,000.

accessedBytesLimit
number

The monthly limit on your total number of Parcel data bytes accessed, from both document upload and download operations. By default, this is set to 100GB.

computeMsecLimit
number

The monthly limit on your total number of Parcel compute time utilized. By default this is set to 100,000 seconds.

Responses

Request samples

Content type
application/json
{
  • "apiCallsLimit": 0,
  • "accessedBytesLimit": 0,
  • "computeMsecLimit": 0
}

Response samples

Content type
application/json
{
  • "apiCallsLimit": 0,
  • "accessedBytesLimit": 0,
  • "computeMsecLimit": 0
}

tokens

Creation of and operations on data tokens, a layer atop Parcel.

Return linked Ethereum addresses.

Authorizations:
AccessToken (parcel.safe)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Link a new Ethereum address.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

Request Body schema: application/json

Proof of ownership of the Ethereum account.

proof
required
string <hex>

An hex-encoded signature of the string parcel identity = <your identity id>, made using web3_personalSign.

Responses

Request samples

Content type
application/json
{
  • "proof": "0x0b712114734b34fc51a16d32e22f428a28caffdf0c608e42ff16bed204a6b728666077fc966147f4e533e68452341da2e6d064f1a9410456d35476759d0f62f61b"
}

Response samples

Content type
application/json
{
  • "address": "0x16355dda54b8421f8e173d12b96371a36f76d633"
}

Unlink the specified Ethereum address.

Authorizations:
AccessToken (parcel.full)
path Parameters
identityId
required
string (IdentityId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of the identity.

ethereumAddress
required
string <hex>
Example: 0x16355dda54b8421f8e173d12b96371a36f76d633

An Ethereum address representing a linked identity.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the token balances held by the identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return the token balance held by the identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "token": "TVehZvHzZ2ADnjZx1qoLrTq",
  • "balance": 0
}

Initiate a token transfer.

An alias for POST /tokens/{tokenId}/transfers.

Authorizations:
AccessToken (parcel.full)
path Parameters
required
IdentityId (string) or AppId (string) (IdentityOrAppId)
Example: IPoxXkdvFsrqzDdU7h3QqSs

The unique identifier of an identity or app.

tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

Request Body schema: application/json
required
Array of objects (IdentityTokenVerifier)

Responses

Request samples

Content type
application/json
{
  • "id": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "tokenVerifiers": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Mint a token.

Authorizations:
AccessToken (parcel.safe)
Request Body schema: application/json
name
string

The optional display name of the token.

required
object

The parameters of the grant made to holders of the token on the underlying assets.

consumesAssets
boolean
Default: false

If set to true, the capability to mint more tokens backed by any contained asset is dropped. This field would be set if the data were impossible to recreate (e.g., the output of a job using a time-dependent grant/data source) and you wanted to enforce scarcity (and hence obtain a higher token price, for instance).

This field's claim is vacuous if the data is not irreplaceable, as the data owner can re-upload the data and make a new token. Of course, it's a new token.

required
ParcelTransferability (object) or RemoteTransferability (object)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "grant": {
    },
  • "consumesAssets": false,
  • "transferability": {
    }
}

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "string",
  • "grant": {
    },
  • "consumesAssets": false,
  • "transferability": {
    },
  • "id": "TVehZvHzZ2ADnjZx1qoLrTq"
}

Return information about a token.

Authorizations:
AccessToken (parcel.public)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "name": "string",
  • "grant": {
    },
  • "consumesAssets": false,
  • "transferability": {
    },
  • "id": "TVehZvHzZ2ADnjZx1qoLrTq"
}

Destroy the token.

Delists the token for which the caller holds all supply. If a backing asset is no longer part of any token, it will again be transferrable from the escrow identity by the original owner.

Authorizations:
AccessToken (parcel.full)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Return the assets backing a token.

Authorizations:
AccessToken (parcel.public)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

query Parameters
object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Add an asset to a token.

Adds an asset to the token. The asset must be owned by the escrow identity and be tokenizable by the caller.

If this token consumes its assets, this asset cannot be tokenized again.

Authorizations:
AccessToken (parcel.safe)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

required
DocumentId (string) or DatabaseId (string) (AssetId)
Example: DNa4FTGpmYjHeEfqihq6o5y

The unique identifier of a data asset.

Responses

Response samples

Content type
application/json
{
  • "asset": "DSgUhs1oiQ8vr5pQH8pgfgs",
  • "token": "TVehZvHzZ2ADnjZx1qoLrTq",
  • "consumed": true
}

Remove the asset from the token.

Removes an asset from a token for which the caller holds all supply. If no other tokens hold this asset, the original owner will again be able to retrieve the it from the escrow identity.

Authorizations:
AccessToken (parcel.full)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

required
DocumentId (string) or DatabaseId (string) (AssetId)
Example: DNa4FTGpmYjHeEfqihq6o5y

The unique identifier of a data asset.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

List completed token transfers.

Authorizations:
AccessToken (parcel.public)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

query Parameters
object

The filter to apply, if any.

object

Controls the number of results returned and after what offset

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Initiate a token transfer.

Transfers some tokens from the caller to the recipient. Tokens can only be transferred using this method if the token is not already bridged to another network. If the token has been bridged, transfer the bridged token on the other network instead.

Authorizations:
AccessToken (parcel.full)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

Request Body schema: application/json
required
IdentityId (string) or AppId (string) or EscrowAccount (string)

The recipient of the tokens. Sending to the escrow identity makes the tokens inaccessible (c.f. burning).

amount
required
integer <int64> >= 0

Responses

Request samples

Content type
application/json
{
  • "recipient": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "amount": 1
}

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "id": "RWnbsy4fS6UknkBkBYYEUoB",
  • "token": "TVehZvHzZ2ADnjZx1qoLrTq",
  • "sender": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "recipient": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "amount": 0,
  • "bridgeTransactionId": "string"
}

Return a transfer receipt.

Authorizations:
AccessToken (parcel.public)
path Parameters
tokenId
required
string (TokenId)
Example: TVehZvHzZ2ADnjZx1qoLrTq

The unique identifier of the Parcel data-backed token.

transferReceiptId
required
string (TransferReceiptId)
Example: RWnbsy4fS6UknkBkBYYEUoB

The unique identifier of a token transfer.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "id": "RWnbsy4fS6UknkBkBYYEUoB",
  • "token": "TVehZvHzZ2ADnjZx1qoLrTq",
  • "sender": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "recipient": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "amount": 0,
  • "bridgeTransactionId": "string"
}

Return a transfer receipt.

Authorizations:
AccessToken (parcel.public)
path Parameters
transferReceiptId
required
string (TransferReceiptId)
Example: RWnbsy4fS6UknkBkBYYEUoB

The unique identifier of a token transfer.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2020-12-09T09:51:41.000Z",
  • "id": "RWnbsy4fS6UknkBkBYYEUoB",
  • "token": "TVehZvHzZ2ADnjZx1qoLrTq",
  • "sender": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "recipient": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "amount": 0,
  • "bridgeTransactionId": "string"
}

Search available tokens.

Return information about data tokens that match the (optional) filter.

Authorizations:
AccessToken (parcel.public)
query Parameters
object

Controls the number of results returned and after what offset

Request Body schema: application/json
IdentityId (string) or AppId (string) or EscrowAccount (string)

Search for tokens held by the provided identity.

object

Search for tokens backed by documents matching the provided search parameters.

Responses

Request samples

Content type
application/json
{
  • "heldBy": "IPoxXkdvFsrqzDdU7h3QqSs",
  • "containsAsset": {
    }
}

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Search for escrowed assets.

Return information about assets held by the escrow identity that match the (optional) filter.

Authorizations:
AccessToken (parcel.public)
query Parameters
object

Controls the number of results returned and after what offset

Request Body schema: application/json
selectedByCondition
object

Search for documents that would be selected if a grant with the specified condition were created. Use this field for simulating a grant.

If accessibleInContext is also specified, this field selects documents both accessible in the context and selected by the condition (i.e. existing conditions apply).

object

Search for documents that can be accessed in the provided context. This field allows you to discover documents that you can access either yourself, or from a job.

token
string

Search for assets present in this token.

Responses

Request samples

Content type
application/json
{
  • "selectedByCondition": {
    },
  • "accessibleInContext": {
    }
}

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "results": [
    ]
}

Return a data asset held by the escrow identity.

Returns information about a a data asset held by the escrow identity.

Authorizations:
AccessToken (parcel.public)
path Parameters
required
DocumentId (string) or DatabaseId (string) (AssetId)
Example: DNa4FTGpmYjHeEfqihq6o5y

The unique identifier of a data asset.

Responses

Response samples

Content type
application/json
{
  • "id": "DSgUhs1oiQ8vr5pQH8pgfgs",
  • "type": "document",
  • "claimant": "IPoxXkdvFsrqzDdU7h3QqSs"
}