Autotask API Reference

The Autotask API allows you to programmatically list, create, retrieve, update, delete Autotasks, in addition to uploading new code to any of your Autotasks.

Requests need to be authenticated with a bearer token, which is negotiated from the Team API Key with the corresponding capability. Refer to the authentication section for info on how to negotiate it.

We recommend you use the @openzeppelin/defender-autotask-client npm package for simplifying interactions with the Autotask API.
It is not recommended to use the @openzeppelin/defender-autotask-client npm package in a browser environment as sensitive keys would be exposed publicly.

Create Endpoint

The autotasks endpoint is used for creating a new Autotask via a POST request. The endpoint accepts the following interface:

interface CreateAutotaskRequest {
  name: string;
  encodedZippedCode: string;
  relayerId?: string;
  trigger: {
    type: 'schedule' | 'webhook';
    frequencyMinutes?: number;
    cron?: string;
  };
  paused: boolean;
  environmentVariables?: {[key: string]: string};
}

Using the @openzeppelin/defender-autotask-client, you can call the create endpoint as such:

const myAutotask = {
  name: "my-autotask",
  encodedZippedCode: await client.getEncodedZippedCodeFromFolder('./code'),
  trigger: {
    type: 'schedule',
    frequencyMinutes: 1500,
  },
  paused: false,
  environmentVariables: {
    hello: "world!"
  }
};
await client.create(myAutotask);

Environment Variables Endpoint

Using the @openzeppelin/defender-autotask-client, you can call the updateEnvironmentVariables and getEnvironmentVariables endpoint as such:

await client.updateEnvironmentVariables('autotaskId', { hello: 'world!', test: '123' });
await client.getEnvironmentVariables('autotaskId');
Environment variables, as opposed to autotask secrets, are unencrypted and scoped to the individual autotask. They are accessible from the autotask code via process.env.

List Endpoint

The autotasks endpoint is used for retrieving an Autotask via a GET request.

Using the @openzeppelin/defender-autotask-client, you can call the list endpoint as such:

await client.list();

An example response:

{
  items: [
    {
      autotaskId: '11ecbea0-7126-4345-a5a5-815898307c9d',
      name: 'Example 1',
      paused: false,
      trigger: [Object],
      relayerId: 'f75701bb-d0bd-49d2-bec9-3420a7b645f6'
    },
    {
      autotaskId: '143f7d62-22c1-427e-82e7-20036925c4b3',
      name: 'Example 2',
      paused: false,
      trigger: [Object]
    },
  ],
  keyValueStoreItemsCount: 0,
  runsQuotaUsage: 0
}

Get Endpoint

The autotasks/{id} endpoint is used for retrieving an Autotask via a GET request. The endpoint accepts an autotask Id.

Using the @openzeppelin/defender-autotask-client, you can call the get endpoint as such:

await client.get("671d1f80-99e3-4829-aa15-f01e3298e428");

An example response:

{
  autotaskId: '671d1f80-99e3-4829-aa15-f01e3298e428',
  name: 'my-autotask',
  paused: false,
  trigger: { type: 'schedule', frequencyMinutes: 1500 },
  encodedZippedCode: 'UEsDBAoAAAAAAAFzWFTA91VHFwAAABcAAAAHAAAAZGVwcy5qc2V4cG9ydHMuZm9vID0gKCkgPT4gNDI7UEsDBAoAAAAAAAFzWFSEyiyCiQAAAIkAAAAIAAAAaW5kZXguanNjb25zdCBkZXBzID0gcmVxdWlyZSgnLi9kZXBzJyk7CgpleHBvcnRzLmhhbmRsZXIgPSBhc3luYyBmdW5jdGlvbigpIHsKICBjb25zdCB2YWx1ZSA9IGRlcHMuZm9vKCk7CiAgY29uc29sZS5sb2codmFsdWUpOwogIHJldHVybiB2YWx1ZTsKfVBLAQIUAAoAAAAAAAFzWFTA91VHFwAAABcAAAAHAAAAAAAAAAAAAAAAAAAAAABkZXBzLmpzUEsBAhQACgAAAAAAAXNYVITKLIKJAAAAiQAAAAgAAAAAAAAAAAAAAAAAPAAAAGluZGV4LmpzUEsFBgAAAAACAAIAawAAAOsAAAAAAA==',
  environmentVariables: { hello: 'world!', test: '123' }
}

Update Endpoint

The autotasks endpoint is used for updating an Autotask via a PUT request. The endpoint accepts the following interface:

interface UpdateAutotaskRequest {
  autotaskId: string;
  name: string;
  encodedZippedCode?: string;
  relayerId?: string;
  trigger: {
    type: 'schedule' | 'webhook';
    frequencyMinutes?: number;
    cron?: string;
  };
  paused: boolean;
}

Using the @openzeppelin/defender-autotask-client, you can call the update endpoint as such:

const myAutotask = {
  autotaskId: "671d1f80-99e3-4829-aa15-f01e3298e428",
  name: "my-autotask",
  trigger: {
    type: 'schedule',
    frequencyMinutes: 1700,
  },
  paused: true
};
await client.update(myAutotask);

An example response:

{
  autotaskId: '671d1f80-99e3-4829-aa15-f01e3298e428',
  name: 'my-autotask',
  paused: true,
  trigger: { type: 'schedule', frequencyMinutes: 1700 },
  encodedZippedCode: 'UEsDBAoAAAAAAAFzWFTA91VHFwAAABcAAAAHAAAAZGVwcy5qc2V4cG9ydHMuZm9vID0gKCkgPT4gNDI7UEsDBAoAAAAAAAFzWFSEyiyCiQAAAIkAAAAIAAAAaW5kZXguanNjb25zdCBkZXBzID0gcmVxdWlyZSgnLi9kZXBzJyk7CgpleHBvcnRzLmhhbmRsZXIgPSBhc3luYyBmdW5jdGlvbigpIHsKICBjb25zdCB2YWx1ZSA9IGRlcHMuZm9vKCk7CiAgY29uc29sZS5sb2codmFsdWUpOwogIHJldHVybiB2YWx1ZTsKfVBLAQIUAAoAAAAAAAFzWFTA91VHFwAAABcAAAAHAAAAAAAAAAAAAAAAAAAAAABkZXBzLmpzUEsBAhQACgAAAAAAAXNYVITKLIKJAAAAiQAAAAgAAAAAAAAAAAAAAAAAPAAAAGluZGV4LmpzUEsFBgAAAAACAAIAawAAAOsAAAAAAA=='
}

Delete Endpoint

The autotasks/{id} endpoint is used for deleting an Autotask via a DELETE request. The endpoint accepts an autotask Id.

Using the @openzeppelin/defender-autotask-client, you can call the delete endpoint as such:

await client.delete("671d1f80-99e3-4829-aa15-f01e3298e428");

An example response:

  message: '671d1f80-99e3-4829-aa15-f01e3298e428 deleted'

Update Code Endpoint

The autotasks/{id}/code endpoint is used for uploading new Autotask code via a PUT request. The endpoint accepts a JSON object with an encodedZippedCode property, which corresponds to the base64-encoded zip file with the code bundle.

zip -r code.zip index.js

curl \
  -X PUT \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{ \"encodedZippedCode\": \"$(cat code.zip | base64 -w0)\" }" \
    "https://defender-api.openzeppelin.com/autotask/autotasks/${AUTOTASKID}/code"

Or through @openzeppelin/defender-autotask-client as such:

await client.updateCodeFromFolder("671d1f80-99e3-4829-aa15-f01e3298e428", './code');
You can include multiple files in the bundle, as long as the bundle does not exceed 5mb in size (after being compressed and base64-encoded), and you include an index.js at the root of the zip file to act as entrypoint.

Autotask Runs Endpoints

The autotasks/{id}/runs/manual endpoint can be used to trigger an autotask run manually:

curl \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -d "$DATA" \
    "https://defender-api.openzeppelin.com/autotask/autotasks/${AUTOTASKID}/runs/manual"

Or through @openzeppelin/defender-autotask-client as such:

await client.runAutotask("671d1f80-99e3-4829-aa15-f01e3298e428");

Autotask run data can be listed with:

curl \
  -X GET \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $KEY" \
  -H "Authorization: Bearer $TOKEN" \
    "https://defender-api.openzeppelin.com/autotask/autotasks/${AUTOTASKID}/runs"
await client.listAutotaskRuns("671d1f80-99e3-4829-aa15-f01e3298e428");

And logs for a specific run can be fetched with the AUTOTASK_RUN_ID (obtained from list request directly above):

curl \
  -X GET \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $KEY" \
  -H "Authorization: Bearer $TOKEN" \
    "https://defender-api.openzeppelin.com/autotask/autotasks/runs/${AUTOTASK_RUN_ID}"
// this method's argument is the autotask run ID, not autotask ID
await client.getAutotaskRun("ae729f92-11e2-0012-bb16-c98c3298e112");

Secrets Endpoint

The autotasks/secrets endpoint can be used to create and delete (but not fetch) secrets:

curl \
  -X POST \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -d "$DATA" \
    "https://defender-api.openzeppelin.com/autotask/secrets"

Or through @openzeppelin/defender-autotask-client as shown below. Both the deletes array and secrets object are required to be present in the payload, but can contain empty values. For example, these calls are all valid:

await client.createSecrets({ deletes: [], secrets: { foo: 'bar' } });

await client.createSecrets({ deletes: ['foo'], secrets: { baz: 'test' } });

await client.createSecrets({ deletes: ['baz'], secrets: { } });
← Admin
Relay →