Metadata

Metadata as code: retrieve source files, deploy (or check-only) as an async job, deploy history

Component types, source paths and limits of the source format

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/metadata/types" \
  -H "Authorization: Bearer <token>"

{
  "formatVersion": 0,
  "projectFile": "string",
  "defaultSourceDir": "string",
  "schema": "string",
  "limits": {
    "property1": 0,
    "property2": 0
  },
  "types": [
    {}
  ]
}

Retrieve metadata as source files (all types, chosen types or chosen components)

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

typesarray<string>

Types to retrieve (default: all)

componentsarray<object>

Only these components Items: at most 600.

projectNamestring

Project name written into salesos.project.json

Maximum length: 100

curl -X POST "https://api.salesos.org/v1/metadata/retrieve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "types": [
      "CUSTOM_OBJECT"
    ],
    "components": [
      {
        "type": "CUSTOM_OBJECT",
        "key": "string"
      }
    ],
    "projectName": "string"
  }'

{
  "formatVersion": 0,
  "organizationId": "string",
  "retrievedAt": "2019-08-24T14:15:22Z",
  "project": {},
  "sourceDir": "string",
  "files": {
    "property1": "string",
    "property2": "string"
  },
  "components": [
    {
      "type": "string",
      "key": "string",
      "path": "string"
    }
  ]
}

Queue a deploy (or checkOnly validation) of source files; poll GET /metadata/deploys/:id

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

projectobject

Parsed salesos.project.json

filesRequiredobject

Component files relative to the project sourceDir: { "objects/invoice.object.json": "" }

checkOnlyboolean

Validate only; nothing is written

Default: false

activateboolean

New custom actions, hooks and functions start active (functions only when every declared secret is set)

Default: false

destructivearray<object>

Components to delete from the target (destructive changes) Items: at most 200.

labelstring

Shown in deploy history

Maximum length: 200

runTestsstring

Tests to run before anything is written: NONE, SPECIFIED (the package's tests) or ALL (the package's plus the tests earlier deploys left in the org). A failing test fails the deploy.

Default: "SPECIFIED"Value in: "NONE" | "SPECIFIED" | "ALL"

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255

curl -X POST "https://api.salesos.org/v1/metadata/deploy" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {},
    "files": {
      "property1": "string",
      "property2": "string"
    },
    "checkOnly": false,
    "activate": false,
    "destructive": [
      {
        "type": "CUSTOM_OBJECT",
        "key": "string"
      }
    ],
    "label": "string",
    "runTests": "NONE"
  }'

{
  "id": "string",
  "status": "QUEUED",
  "checkOnly": true,
  "activate": true,
  "runTests": "NONE",
  "phase": "string",
  "done": 0,
  "total": 0,
  "label": "string",
  "packageHash": "string",
  "componentCount": 0,
  "summary": {
    "property1": 0,
    "property2": 0
  },
  "errorMessage": "string",
  "rerunOfId": "string",
  "createdById": "string",
  "createdByEmail": "string",
  "createdByName": "string",
  "authMethod": "session",
  "startedAt": "2019-08-24T14:15:22Z",
  "finishedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z"
}

Deploy history, newest first (server-paged)

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

pagestring

Default: 1

limitstring

Default: 20

statusstring

Value in: "QUEUED" | "RUNNING" | "SUCCEEDED" | "FAILED" | "CANCELED"

curl -X GET "https://api.salesos.org/v1/metadata/deploys?page=1&limit=20&status=QUEUED" \
  -H "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "string",
      "status": "QUEUED",
      "checkOnly": true,
      "activate": true,
      "runTests": "NONE",
      "phase": "string",
      "done": 0,
      "total": 0,
      "label": "string",
      "packageHash": "string",
      "componentCount": 0,
      "summary": {
        "property1": 0,
        "property2": 0
      },
      "errorMessage": "string",
      "rerunOfId": "string",
      "createdById": "string",
      "createdByEmail": "string",
      "createdByName": "string",
      "authMethod": "session",
      "startedAt": "2019-08-24T14:15:22Z",
      "finishedAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "total": 0,
  "page": 0,
  "limit": 0,
  "totalPages": 0
}

One deploy: status, progress and the result per component

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

curl -X GET "https://api.salesos.org/v1/metadata/deploys/<string>" \
  -H "Authorization: Bearer <token>"

{
  "id": "string",
  "status": "QUEUED",
  "checkOnly": true,
  "activate": true,
  "runTests": "NONE",
  "phase": "string",
  "done": 0,
  "total": 0,
  "label": "string",
  "packageHash": "string",
  "componentCount": 0,
  "summary": {
    "property1": 0,
    "property2": 0
  },
  "errorMessage": "string",
  "rerunOfId": "string",
  "createdById": "string",
  "createdByEmail": "string",
  "createdByName": "string",
  "authMethod": "session",
  "startedAt": "2019-08-24T14:15:22Z",
  "finishedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "packageAvailable": true,
  "testResults": {
    "runTests": "string",
    "total": 0,
    "passed": 0,
    "failed": 0,
    "durationMs": 0,
    "results": [
      {
        "id": "string",
        "kind": "FUNCTION",
        "name": "string",
        "target": "string",
        "path": "string",
        "source": "package",
        "status": "passed",
        "durationMs": 0,
        "message": "string",
        "details": {}
      }
    ]
  },
  "results": [
    {
      "type": "string",
      "key": "string",
      "name": "string",
      "path": "string",
      "action": "CREATE",
      "status": "planned",
      "problems": [
        {
          "severity": "error",
          "message": "string"
        }
      ],
      "targetId": "string",
      "note": "string"
    }
  ]
}

Re-run a deploy's package as check-only against the org as it is now

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Maximum length: 255

curl -X POST "https://api.salesos.org/v1/metadata/deploys/<string>/check" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

{
  "id": "string",
  "status": "QUEUED",
  "checkOnly": true,
  "activate": true,
  "runTests": "NONE",
  "phase": "string",
  "done": 0,
  "total": 0,
  "label": "string",
  "packageHash": "string",
  "componentCount": 0,
  "summary": {
    "property1": 0,
    "property2": 0
  },
  "errorMessage": "string",
  "rerunOfId": "string",
  "createdById": "string",
  "createdByEmail": "string",
  "createdByName": "string",
  "authMethod": "session",
  "startedAt": "2019-08-24T14:15:22Z",
  "finishedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z"
}

The org policy for deploy tests (component types that need a covering test)

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/metadata/test-policy" \
  -H "Authorization: Bearer <token>"

{
  "requireTestsFor": [
    "FUNCTION"
  ]
}

Require a covering test for every function or flow a deploy creates or changes

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

requireTestsForRequiredarray<string>

Component types a deploy may only create or change when a test in the run covers each one

curl -X PUT "https://api.salesos.org/v1/metadata/test-policy" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "requireTestsFor": [
      "FUNCTION"
    ]
  }'

{
  "requireTestsFor": [
    "FUNCTION"
  ]
}

Cancel a queued deploy

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Maximum length: 255

curl -X POST "https://api.salesos.org/v1/metadata/deploys/<string>/cancel" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

{
  "id": "string",
  "status": "QUEUED",
  "checkOnly": true,
  "activate": true,
  "runTests": "NONE",
  "phase": "string",
  "done": 0,
  "total": 0,
  "label": "string",
  "packageHash": "string",
  "componentCount": 0,
  "summary": {
    "property1": 0,
    "property2": 0
  },
  "errorMessage": "string",
  "rerunOfId": "string",
  "createdById": "string",
  "createdByEmail": "string",
  "createdByName": "string",
  "authMethod": "session",
  "startedAt": "2019-08-24T14:15:22Z",
  "finishedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "packageAvailable": true,
  "testResults": {
    "runTests": "string",
    "total": 0,
    "passed": 0,
    "failed": 0,
    "durationMs": 0,
    "results": [
      {
        "id": "string",
        "kind": "FUNCTION",
        "name": "string",
        "target": "string",
        "path": "string",
        "source": "package",
        "status": "passed",
        "durationMs": 0,
        "message": "string",
        "details": {}
      }
    ]
  },
  "results": [
    {
      "type": "string",
      "key": "string",
      "name": "string",
      "path": "string",
      "action": "CREATE",
      "status": "planned",
      "problems": [
        {
          "severity": "error",
          "message": "string"
        }
      ],
      "targetId": "string",
      "note": "string"
    }
  ]
}

Response

TypeScript

Response

TypeScript

Response

TypeScript

Response

TypeScript

Response

TypeScript

Response

TypeScript

Response

TypeScript

Response

TypeScript

Response

TypeScript