|distinct|boolean|@true@: (default) do not return duplicate objects
@false@: permitted to return duplicates|query|
-h3.(#filters) Available list method filters
+h3(#filters). Available list method filters
The value of the @filters@ parameter is an array of conditions. The @list@ method returns only the resources that satisfy all of the given conditions. In other words, the conjunction @AND@ is implicit.
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/api_client_authorizations@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Object type: @gj3su@
+
+Example UUID: @zzzzz-gj3su-0123456789abcde@
h2. Resource
|last_used_at|datetime|Timestamp of the most recent request using this token.||
|expires_at|datetime|Time at which the token is no longer valid. May be set to a time in the past in order to immediately expire a token.||
|owner_uuid|string|The user associated with the token. All operations using this token are checked against the permissions of this user.||
-|scopes|array|A list of resources this token is allowed to access. A scope of ["all"] allows all resources. See below.||
-
-h3(#scope). Scopes
-
-Scopes can restrict a token so it may only access certain resources. This is in addition to normal permission checks for the user associated with the token.
-
-Each entry in scopes consists of a @request_method@ and @request_path@, where the @request_method@ is a HTTP method (one of @GET@, @POST@, @PUT@ or @DELETE@) and @request_path@ is the request URI. A given request is permitted if it matches a scopes exactly, or the scope ends with @/@ and the request string is a prefix of the scope.
-
-As a special case, a scope of ["all"] allows all resources.
-
-h4. Examples
-
-A scope of @GET /arvados/v1/collections@ permits listing collections.
-
-* Requests with different methods, such as creating a new collection using @POST /arvados/v1/collections@, will be rejected.
-* Requests to access other resources, such as @GET /arvados/v1/groups@, will be rejected.
-* Be aware that requests for specific records, such as @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will also be rejected. This is because the scope @GET /arvados/v1/collections@ does not end in @/@
+|scopes|array|A list of resources this token is allowed to access. A scope of ["all"] allows all resources. See "API Authorization":{{site.baseurl}}/api/tokens.html#scopes for details.||
-A scope of @GET /arvados/v1/collections/@ (with @/@ suffix) will permit access to individual collections.
-
-* The request @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will succeed
-* Be aware that requests for listing @GET /arvados/v1/collections@ (no @/@ suffix) will be rejected, because it is not an exact match with @GET /arvados/v1/collections/@
-
-To allow both listing objects and requesting individual objects, include both in the scope: @["GET /arvados/v1/collections", "GET /arvados/v1/collections/"]@
+h2. Methods
-A narrow scope such as @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will disallow listing objects as well as disallow requesting any object other than those in the scope.
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
-h2. Methods
+Required arguments are displayed in %{background:#ccffcc}green%.
h3(#create). create
Create a new ApiClientAuthorization.
-Regular users may only create self-owned API tokens, but may provide a restricted "scope"#scope . Administrators may create API tokens corresponding to any user.
+Regular users may only create self-owned API tokens, but may provide a restricted "scope":{{site.baseurl}}/api/tokens.html#scopes . Administrators may create API tokens corresponding to any user.
Arguments:
h3. get
-Gets a ApiClientAuthorization's metadata by UUID.
+Gets an ApiClientAuthorization's metadata by UUID.
Arguments:
List api_client_authorizations.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of api_client_authorizations to return.|query||
-|order|string|Order in which to return matching api_client_authorizations.|query||
-|filters|array|Conditions for filtering api_client_authorizations.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/api_clients@
-UUID type: @ozdt8@
+Object type: @ozdt8@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-ozdt8-0123456789abcde@
h2. Resource
The "api_clients" resource determines if web applications that have gone through the browser login flow may create or list API tokens.
-Each ApiClient has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each ApiClient has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new ApiClient.
List api_clients.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of api_clients to return.|query||
-|order|string|Order in which to return matching api_clients.|query||
-|filters|array|Conditions for filtering api_clients.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/authorized_keys@
-UUID type: @fngyi@
+Object type: @fngyi@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-fngyi-0123456789abcde@
h2. Resource
The authorized_keys resource stores SSH public keys which grant access to virtual machines or git repositories on the Arvados cluster as the user in @authorized_user_uuid@.
-Each AuthorizedKey has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each AuthorizedKey has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
-|name|string|||
-|key_type|string|||
-|authorized_user_uuid|string|||
-|public_key|text|||
-|expires_at|datetime|||
+|name|string|A name to help the user manage their keys.||
+|key_type|string|Public key type, currently only supports "SSH"||
+|authorized_user_uuid|string|The user to which this key belongs. Authentication using this key authenticates as this user.||
+|public_key|text|The actual public key material, e.g. from @~/.ssh/id_rsa.pub@||
+|expires_at|datetime|Expiration date after which the key is no longer valid.||
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new AuthorizedKey.
List authorized_keys.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of authorized_keys to return.|query||
-|order|string|Order in which to return matching authorized_keys.|query||
-|filters|array|Conditions for filtering authorized_keys.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/collections@
-UUID type: @4zz18@
+Object type: @4zz18@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-4zz18-0123456789abcde@
h2. Resource
-Collections describe sets of files in terms of data blocks stored in Keep. See "storage in Keep":{{site.baseurl}}/api/execution.html for details.
+Collections describe sets of files in terms of data blocks stored in Keep. See "storage in Keep":{{site.baseurl}}/api/storage.html for details.
-Each collection has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each collection has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
|name|string|||
|description|text|||
-|portable_data_hash|string|The MD5 sum of the stripped manifest text.||
+|portable_data_hash|string|The MD5 sum of the manifest text stripped of block hints other than the size hint.||
|manifest_text|text|||
|replication_desired|number|Minimum storage replication level desired for each data block referenced by this collection. A value of @null@ signifies that the site default replication level (typically 2) is desired.|@2@|
|replication_confirmed|number|Replication level most recently confirmed by the storage system. This field is null when a collection is first created, and is reset to null when the manifest_text changes in a way that introduces a new data block. An integer value indicates the replication level of the _least replicated_ data block in the collection.|@2@, null|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Collection.
List collections.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of collections to return.|query||
-|order|string|Order in which to return matching collections.|query||
-|filters|array|Conditions for filtering collections.|query||
-|select|array|Data fields to return in the result list.|query|@["uuid", "manifest_text"]@|
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
Note: Because adding access tokens to manifests can be computationally expensive, the @manifest_text@ field is not included in results by default. If you need it, pass a @select@ parameter that includes @manifest_text@.
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/container_requests@
-UUID type: @xvhdp@
+Object type: @xvhdp@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-xvhdp-0123456789abcde@
h2. Resource
A container request is a request for the Arvados cluster to perform some computational work. See "computing with Crunch":{{site.baseurl}}/api/execution.html for details.
-Each ContainerRequest offers the following attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each ContainerRequest offers the following attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
All attributes are optional, unless otherwise marked as required.
|properties|hash|Client-defined structured data that does not affect how the container is run.||
|state|string|The allowed states are "Uncommitted", "Committed", and "Final".|Once a request is Committed, the only attributes that can be modified are priority, container_uuid, and container_count_max. A request in the "Final" state cannot have any of its functional parts modified (i.e., only name, description, and properties fields can be modified).|
|requesting_container_uuid|string|The uuid of the parent container that created this container_request, if any. Represents a process tree.|The priority of this container_request is inherited from the parent container, if the parent container is cancelled, this container_request will be cancelled as well.|
-|container_uuid|string|The uuid of the container that satisfies this container_request. The system will find and reuse any preexisting Container that matches this ContainerRequest's criteria. See "Container reuse":#container_reuse for more details.|Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported.|
+|container_uuid|string|The uuid of the container that satisfies this container_request. The system will find and reuse any preexisting Container that matches this container request's criteria. See "Container reuse":#container_reuse for more details.|Currently, container reuse is the default behavior and a mechanism to skip reuse is not supported.|
|container_count_max|integer|Maximum number of containers to start, i.e., the maximum number of "attempts" to be made.||
|mounts|hash|Objects to attach to the container's filesystem and stdin/stdout.|See "Mount types":#mount_types for more details.|
|runtime_constraints|hash|Restrict the container's access to compute resources and the outside world.|Required when in "Committed" state. e.g.,<pre><code>{
|cwd|string|Initial working directory, given as an absolute path (in the container) or a path relative to the WORKDIR given in the image's Dockerfile.|Required.|
|command|array of strings|Command to execute in the container.|Required. e.g., @["echo","hello"]@|
|output_path|string|Path to a directory or file inside the container that should be preserved as container's output when it finishes. This path must be, or be inside, one of the mount targets. For best performance, point output_path to a writable collection mount.|Required.|
-|priority|integer|Higher value means spend more resources on this container_request, i.e., go ahead of other queued containers, bring up more nodes etc.|Priority 0 means a container should not be run on behalf of this request. Clients are expected to submit ContainerRequests with zero priority in order to prevew the container that will be used to satisfy it. Priority can be null if and only if state!="Committed".|
+|priority|integer|Higher value means spend more resources on this container_request, i.e., go ahead of other queued containers, bring up more nodes etc.|Priority 0 means a container should not be run on behalf of this request. Clients are expected to submit container requests with zero priority in order to prevew the container that will be used to satisfy it. Priority can be null if and only if state!="Committed".|
|expires_at|datetime|After this time, priority is considered to be zero.|Not yet implemented.|
|use_existing|boolean|If possible, use an existing (non-failed) container to satisfy the request instead of creating a new one.|Default is true|
@true@
h2(#container_reuse). Container reuse
-When a ContainerRequest is "Committed", the system will try to find and reuse any preexisting Container with the same exact command, cwd, environment, output_path, container_image, mounts, and runtime_constraints as this ContainerRequest. The serialized fields environment, mounts and runtime_constraints are sorted to facilitate comparison.
+When a container request is "Committed", the system will try to find and reuse any preexisting Container with the same exact command, cwd, environment, output_path, container_image, mounts, and runtime_constraints as this container request. The serialized fields environment, mounts and runtime_constraints are sorted to facilitate comparison.
-The system will use the following scheme to determine which Container to consider for reuse: A Container with the same exact command, cwd, environment, output_path, container_image, mounts, and runtime_constraints as this ContainerRequest and,
+The system will use the following scheme to determine which Container to consider for reuse: A Container with the same exact command, cwd, environment, output_path, container_image, mounts, and runtime_constraints as this container request and,
* The oldest successfully finished container, i.e., in state "Complete" with exit_code of 0. If matching containers with different outputs are found, the system will forgo reusing any of these finished containers and instead look for suitable containers in other states
* The oldest "Running" container with the highest progress, i.e., the container that is most likely to finish first
* The oldest "Locked" container with the highest priority, i.e., the container that is most likely to start first
* The oldest "Queued" container with the highest priority, i.e, the container that is most likely to start first
-h2(#cancel_container). Canceling a ContainerRequest
+h2(#cancel_container). Canceling a container request
-A ContainerRequest may be canceled by setting it's priority to 0, using an update call.
+A container request may be canceled by setting it's priority to 0, using an update call.
-When a ContainerRequest is canceled, it will still reflect the state of the Container it is associated with via the container_uuid attribute. If that Container is being reused by any other container_requests that are still active, i.e., not yet canceled, that Container may continue to run or be scheduled to run by the system in future. However, if no other container_requests are using that Contianer, then the Container will get canceled as well.
+When a container request is canceled, it will still reflect the state of the Container it is associated with via the container_uuid attribute. If that Container is being reused by any other container_requests that are still active, i.e., not yet canceled, that Container may continue to run or be scheduled to run by the system in future. However, if no other container_requests are using that Contianer, then the Container will get canceled as well.
h2. Methods
+
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h2(#create). create
-Create a new ContainerRequest.
+Create a new container request.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|container_request|object|See "ContainerRequest resource":{{site.baseurl}}/api/schema/ContainerRequest.html|request body||
+{background:#ccffcc}.|container_request|object|Container request resource.|request body||
+
The request body must include the required attributes command, container_image, cwd, and output_path. It can also inlcude other attributes such as environment, mounts, and runtime_constraints.
h3. delete
-Delete an existing ContainerRequest.
+Delete an existing container request.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
+{background:#ccffcc}.|uuid|string|The UUID of the container request in question.|path||
h3. get
-Get a ContainerRequest's metadata by UUID.
+Get a container request's metadata by UUID.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
+{background:#ccffcc}.|uuid|string|The UUID of the container request in question.|path||
h3. list
List container_requests.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of container_requests to return.|query||
-|order|string|Order in which to return matching container_requests.|query||
-|filters|array|Conditions for filtering container_requests.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
-See the create method documentation for more information about ContainerRequest-specific filters.
+See the create method documentation for more information about container request-specific filters.
h3. update
-Update attributes of an existing ContainerRequest.
+Update attributes of an existing container request.
Arguments:
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string|The UUID of the ContainerRequest in question.|path||
+{background:#ccffcc}.|uuid|string|The UUID of the container request in question.|path||
|container_request|object||query||
{% include 'notebox_begin' %}
Setting the priority of a committed container_request to 0 may cancel a running container assigned for it.
-See "Canceling a ContainerRequest":{{site.baseurl}}/api/schema/ContainerRequest.html#cancel_container for further details.
+See "Canceling a container request":{{site.baseurl}}/api/methods/container_requests.html#cancel_container for further details.
{% include 'notebox_end' %}
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/containers@
-UUID type: @dz642@
+Object type: @dz642@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-dz642-0123456789abcde@
h2. Resource
A container is work order to be dispatched to an Arvados cluster to perform some computational work. A container is created in response to a container request. See "computing with Crunch":{{site.baseurl}}/api/execution.html for details.
-Each Container offers the following attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Container offers the following attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Notes|
h2(#runtime_constraints). {% include 'container_runtime_constraints' %}
h2. Methods
+
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h2(#create). create
Create a new Container.
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|container|object|See "Container resource":{{site.baseurl}}/api/schema/Container.html|request body||
+{background:#ccffcc}.|container|object|Container resource|request body||
h3. delete
List containers.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of containers to return.|query||
-|order|string|Order in which to return matching containers.|query||
-|filters|array|Conditions for filtering containers.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
See the create method documentation for more information about Container-specific filters.
title: "groups"
...
-
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/groups@
-UUID type: @j7d0g@
+Object type: @j7d0g@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-j7d0g-0123456789abcde@
h2. Resource
Groups provides a way to apply the same permissions to a set of Arvados objects. See "permission model":{{site.baseurl}}/api/permission-model.html for details.
-Each Group has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Group has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. contents
Retrieve a list of items owned by the group.
List groups.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of groups to return.|query||
-|order|string|Order in which to return matching groups.|query||
-|filters|array|Conditions for filtering groups.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. show
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/humans@
-UUID type: @7a9it@
+Object type: @7a9it@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-7a9it-0123456789abcde@
h2. Resource
A metadata record that may be used to represent a human subject.
-Each Human has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Human has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Human.
List humans.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of humans to return.|query||
-|order|string|Order in which to return matching humans.|query||
-|filters|array|Conditions for filtering humans.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/job_tasks@
-UUID type: @ot0gb@
+Object type: @ot0gb@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-ot0gb-0123456789abcde@
h2. Resource
Deprecated.
-A job task is a individually scheduled and task executed as part of an overall job.
+A job task is a individually scheduled unit of work executed as part of an overall job.
-Each JobTask has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each JobTask has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
|job_uuid|string|||
|created_by_job_task_uuid|string|||
+h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
-h2. Methods
+Required arguments are displayed in %{background:#ccffcc}green%.
h3. create
List job_tasks.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of job_tasks to return.|query||
-|order|string|Order in which to return matching job_tasks.|query||
-|filters|array|Conditions for filtering job_tasks.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/jobs@
-UUID type: @8i9sb@
+Object type: @8i9sb@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-8i9sb-0123456789abcde@
h2. Resource
A job describes a work order to be executed by the Arvados cluster.
-Each job has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each job has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Notes|
|min_ram_per_task|integer|Minimum real memory (KiB) per task||
h2. Methods
+
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. cancel
Cancel a job that is queued or running.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string||path||
-h2(#create). create
+h3(#create). create
Create a new Job.
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|job|object|See "Job resource":{{site.baseurl}}/api/schema/Job.html|request body||
+{background:#ccffcc}.|job|object|Job resource|request body||
|minimum_script_version |string |Git branch, tag, or commit hash specifying the minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.[1]|query|@"c3e86c9"@|
|exclude_script_versions|array of strings|Git commit branches, tags, or hashes to exclude when deciding whether to re-use a past job.|query|@["8f03c71","8f03c71"]@
@["badtag1","badtag2"]@|
fn1. See the "note about specifying Git commits on the Job resource page":{{site.baseurl}}/api/schema/Job.html#script_version for more detail.
-h3. Specialized filters
+h4. Specialized filters
Special filter operations are available for specific Job columns.
* @docker_image_locator@ @not in docker@ @SEARCH@<br>Negate the @in docker@ filter.
-h3. Reusing jobs
+h4. Reusing jobs
Because Arvados records the exact version of the script, input parameters, and runtime environment that was used to run the job, if the script is deterministic (meaning that the same code version is guaranteed to produce the same outputs from the same inputs) then it is possible to re-use the results of past jobs, and avoid re-running the computation to save time. Arvados uses the following algorithm to determine if a past job can be re-used:
</div>
-h3. Examples
+h4. Examples
Run the script "crunch_scripts/hash.py" in the repository "you" using the "master" commit. Arvados should re-use a previous job if the script_version of the previous job is the same as the current "master" commit. This works irrespective of whether the previous job was submitted using the name "master", a different branch name or tag indicating the same commit, a SHA-1 commit hash, etc.
List jobs.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of jobs to return.|query||
-|order|string|Order in which to return matching jobs.|query||
-|filters|array|Conditions for filtering jobs.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
See the create method documentation for more information about Job-specific filters.
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/keep_disks@
-UUID type: @penuu@
+Object type: @penuu@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-penuu-0123456789abcde@
h2. Resource
Obsoleted by "keep_services":{{site.baseurl}}/api/methods/keep_services.html
-Each KeepDisk has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each KeepDisk has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new KeepDisk.
List keep_disks.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of keep_disks to return.|query||
-|order|string|Order in which to return matching keep_disks.|query||
-|filters|array|Conditions for filtering keep_disks.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. ping
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/keep_services@
-UUID type: @bi6l4@
+Object type: @bi6l4@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-bi6l4-0123456789abcde@
h2. Resource
-The keep_services resource storage servers and proxies available on the cluster for persistent storage and retrieval of keep blocks.
+The keep_services resource keep clients to discover storage servers and proxies available on the cluster for persistent storage and retrieval of keep blocks.
-Each KeepService has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each KeepService has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
-|service_host|string|||
-|service_port|integer|||
-|service_ssl_flag|boolean|||
-|service_type|string|||
+|service_host|string|hostname of the server||
+|service_port|integer|TCP port of the service||
+|service_ssl_flag|boolean|if the server uses SSL||
+|service_type|string|The service type, one of "disk", "blob" (cloud object store) or "proxy" (keepproxy)||
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. accessible
Get a list of keep services that are accessible to the requesting client. Unlike @list@, this is context-sensitive based on the requester, for example providing the list of actual Keep servers when inside the cluster, but providing a proxy service if client contacts Arvados from outside the cluster.
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-
h3. create
Create a new KeepService.
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|keep_disk|object||query||
+|keep_service|object||query||
h3. delete
List keep_services.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of keep_services to return.|query||
-|order|string|Order in which to return matching keep_services.|query||
-|filters|array|Conditions for filtering keep_services.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@
-UUID type: @o0j2j@
+Object type: @o0j2j@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-o0j2j-0123456789abcde@
h2. Resource
Links are an extensible way to describe relationships between Arvados objects and metadata about individual objects.
-Each link has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each link has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|
-|tail_uuid|string|Object UUID at the tail (start, source, origin) of this link|
-|link_class|string|Class (see below)|
-|name|string|Link type (see below)|
-|head_uuid|string|Object UUID at the head (end, destination, target) of this link|
+|head_uuid|string|The object being described or acted on.|
+|tail_uuid|string|The origin or actor in the description or action (may be null).|
+|link_class|string|Type of link|
+|name|string|Primary value of the link.|
|properties|hash|Additional information, expressed as a key→value hash. Key: string. Value: string, number, array, or hash.|
h2. Link classes
Some classes are pre-defined by convention and have standard meanings attached to names.
-h3. provenance
-
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|→Collection |provided → _collection uuid_
-{url→http://example.com/foo.tgz, retrieved_at→1352616640.000}||
-|Job→Collection |provided → _collection uuid_||
-|Specimen→Collection|provided → _collection uuid_||
-|Human→Specimen |provided → _specimen uuid_||
-|Human→Collection |provided → _collection uuid_||
-
h3. permission
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|User→Group |{white-space:nowrap}. can_manage → _group uuid_|The User can read, write, and control permissions on the Group itself, every object owned by the Group, and every object on which the Group has _can_manage_ permission.|
-|User→Group |can_read → _group uuid_ |The User can retrieve the Group itself and every object that is readable by the Group.|
-|User→Job|can_write → _job uuid_ |The User can read and update the Job. (This works for all objects, not just jobs.)|
-|User→Job|can_manage → _job uuid_ |The User can read, update, and change permissions for the Job. (This works for all objects, not just jobs.)|
-|Group→Job|can_manage → _job uuid_ |Anyone with _can_manage_ permission on the Group can also read, update, and change permissions for the Job. Anyone with _can_read_ permission on the Group can read the Job. (This works for all objects, not just jobs.)|
-
-h3. resources
-
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|User→Collection|wants → _collection uuid_ |Determines whether data can be deleted|
-|User→Job |wants → _job uuid_ |Determines whether a job can be cancelled|
+See "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model.
h3. tag
|→Collection | _tag name_ → _collection uuid_|
|→Job | _tag name_ → _job uuid_|
-h3. human_trait
-
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|Human→Trait |measured → _trait uuid_ {value→1.83, unit→metre, measured_at→1352616640.000}||
-
-h3. identifier
-
-table(table table-bordered table-condensed).
-|_. tail_type→head_type|_. name→head_uuid {properties}|_. Notes|
-|→Human |hu123456 → _human uuid_||
+h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
-h2. Methods
+Required arguments are displayed in %{background:#ccffcc}green%.
h3. create
List links.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of links to return.|query||
-|order|string|Order in which to return matching links.|query||
-|filters|array|Conditions for filtering links.|query||
-
-h3. render_not_found
-
-render_not_found links
-
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|a|string||path||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/logs@
-UUID type: @57u5n@
+Object type: @57u5n@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-57u5n-0123456789abcde@
h2. Resource
-Each Log has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Log has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
-|object_uuid|string|||
+|object_uuid|string|The arvados object that is the subject of the log.||
|event_at|datetime|||
|event_type|string|A user-defined category or type for this event.|@LOGIN@|
|summary|text|||
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new log entry.
List log entries.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of log entries to return.|query||
-|order|string|Order in which to return matching log entries.|query||
-|filters|array|Conditions for filtering log entries.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/nodes@
-UUID type: @7ekkf@
+Object type: @7ekkf@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-7ekkf-0123456789abcde@
h2. Resource
Node resources list compute nodes on which Crunch may schedule work.
-Each Node has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Node has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Node.
List nodes.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of nodes to return.|query||
-|order|string|Order in which to return matching nodes.|query||
-|filters|array|Conditions for filtering nodes.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. ping
-ping nodes
+Process a ping from a compute node.
Arguments:
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_instances@
-UUID type: @d1hrv@
+Object type: @d1hrv@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-d1hrv-0123456789abcde@
h2. Resource
Deprecated. A pipeline instance is a collection of jobs managed by @aravdos-run-pipeline-instance@.
-Each PipelineInstance has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each PipelineInstance has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
-|pipeline_template_uuid|string|||
+|pipeline_template_uuid|string|The "pipeline template":pipeline_template.html that this instance was created from.||
|name|string|||
|components|hash|||
|success|boolean|||
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new PipelineInstance.
List pipeline_instances.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of pipeline_instances to return.|query||
-|order|string|Order in which to return matching pipeline_instances.|query||
-|filters|array|Conditions for filtering pipeline_instances.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_templates@
-UUID type: @p5p6p@
+Object type: @p5p6p@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-p5p6p-0123456789abcde@
h2. Resource
Deprecated. A pipeline template is a collection of jobs that can be instantiated as a pipeline_instance.
-Each PipelineTemplate has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each PipelineTemplate has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new PipelineTemplate.
List pipeline_templates.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of pipeline_templates to return.|query||
-|order|string|Order in which to return matching pipeline_templates.|query||
-|filters|array|Conditions for filtering pipeline_templates.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/repositories@
-UUID type: @s0uqq@
+Object type: @s0uqq@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-s0uqq-0123456789abcde@
h2. Resource
The repositories resource lists git repositories managed by Arvados.
-Each Repository has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Repository has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Repository.
List repositories.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of repositories to return.|query||
-|order|string|Order in which to return matching repositories.|query||
-|filters|array|Conditions for filtering repositories.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
navsection: api
navmenu: API Methods
title: "specimens"
-
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
-UUID type: @j58dm@
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/specimens@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Object type: @j58dm@
+
+Example UUID: @zzzzz-j58dm-0123456789abcde@
h2. Resource
A metadata record that may be used to represent a biological specimen.
-Each Specimen has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Specimen has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Specimen.
List specimens.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of specimens to return.|query||
-|order|string|Order in which to return matching specimens.|query||
-|filters|array|Conditions for filtering specimens.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/traits@
-UUID type: @q1cn2@
+Object type: @q1cn2@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-q1cn2-0123456789abcde@
h2. Resource
A metadata record that may be used to represent a genotype or phenotype trait.
-Each Trait has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Trait has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Trait.
List traits.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of traits to return.|query||
-|order|string|Order in which to return matching traits.|query||
-|filters|array|Conditions for filtering traits.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
navsection: api
navmenu: API Methods
title: "users"
-
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/users@
-UUID type: @tpzed@
+Object type: @tpzed@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-tpzed-0123456789abcde@
h2. Resource
Users represent individuals with access to the Arvados cluster.
-Each User has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each User has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new User.
List users.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of users to return.|query||
-|order|string|Order in which to return matching users.|query||
-|filters|array|Conditions for filtering users.|query||
-
-h3. show
-
-show users
-
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|uuid|string||path||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. system
-system users
+Get the user record for the "system user.":{{site.baseurl}}/api/permission-model.html#system
Arguments:
navsection: api
navmenu: API Methods
title: "virtual_machines"
-
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/virtual_machines@
-UUID type: @2x53u@
+Object type: @2x53u@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-2x53u-0123456789abcde@
h2. Resource
-The virtual_machines resource lists nodes in the Arvados cluster to which a user may log in to get an interactive shell (via ssh or webshell).
+The virtual_machines resource lists compute resources in the Arvados cluster to which a user may log in to get an interactive shell (via ssh or webshell).
-Each VirtualMachine has, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each VirtualMachine has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
|hostname|string|||
+h2. Methods
+
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
-h2. create
+h3. create
Create a new VirtualMachine.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
|virtual_machine|object||query||
-h2. delete
+h3. delete
Delete an existing VirtualMachine.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the VirtualMachine in question.|path||
-h2. get
+h3. get
Gets a VirtualMachine's metadata by UUID.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the VirtualMachine in question.|path||
-h2(#logins). logins
+h3(#logins). logins
Get a list of SSH keys and account names that should be able to log in to a given virtual machine.
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string||path||
-The response is a "resource list":{{site.baseurl}}/api/resources.html#resourceList with @kind@ set to @"arvados#HashList"@. Each item is a hash with the following keys:
+The response is an object with the field @items@ containing an array of objects in the following format:
table(table table-bordered table-condensed).
|_. Key|_. Value type|_. Description|_. Example|
|hostname|string|Hostname of the virtual machine|@"shell.xyzzy.arvadosapi.com"@|
|public_key|string|SSH public key|@"ssh-rsa AAAAB3NzaC1yc2E..."@|
|user_uuid|string|UUID of the user who should be able to log in|@"xyzzy-tpzed-mv4d7dy7n91te11"@|
-|virtual_machine_uuid|string|UUID of the "VirtualMachine resource":{{site.baseurl}}/api/schema/VirtualMachine.html|@"xyzzy-2x53u-kvszmclnbjuv8xc"@|
-|authorized_key_uuid|string|UUID of the "AuthorizedKey resource":{{site.baseurl}}/api/schema/AuthorizedKey.html|@"xyzzy-fngyi-v9p0cyfmjxbio64"@|
+|virtual_machine_uuid|string|UUID of the "virtual machine resource":{{site.baseurl}}/api/methods/virtual_machines.html|@"zzzzz-2x53u-kvszmclnbjuv8xc"@|
+|authorized_key_uuid|string|UUID of the "authorized key resource":{{site.baseurl}}/api/methods/authorized_keys.html|@"zzzzz-fngyi-v9p0cyfmjxbio64"@|
-h2. get_all_logins
+h3. get_all_logins
-Get a list, for every virtual machine in the system, of SSH keys and account names that should be able to log in.
+Get a list of SSH keys and account names that should be able to log in for every virtual machine in the system.
Arguments: none.
The response has the same format as the response to the "logins method":#logins above.
-h2. list
+h3. list
List virtual_machines.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of virtual_machines to return.|query||
-|order|string|Order in which to return matching virtual_machines.|query||
-|filters|array|Conditions for filtering virtual_machines.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
-h2. update
+h3. update
Update attributes of an existing VirtualMachine.
navsection: api
navmenu: API Methods
title: "workflows"
-
...
-See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html
-
API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/workflows@
-UUID type: @7fd4e@
+Object type: @7fd4e@
-Required arguments are displayed in %{background:#ccffcc}green%.
+Example UUID: @zzzzz-7fd4e-0123456789abcde@
h2. Resource
Stores a "Common Workflow Language":http://commonwl.org (CWL) computational workflow that can be searched for, browsed and executed (submitted to Crunch) from the workbench.
-Each Workflow offers the following optional attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html:
+Each Workflow offers the following optional attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|_. Example|
h2. Methods
+See "Common resource methods":{{site.baseurl}}/api/methods.html more information about @create@, @delete@, @get@, @list@, and @update@.
+
+Required arguments are displayed in %{background:#ccffcc}green%.
+
h3. create
Create a new Workflow.
table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
-{background:#ccffcc}.|workflow|object|See "Workflow resource":{{site.baseurl}}/api/schema/Workflow.html|request body||
+{background:#ccffcc}.|workflow|object|Workflow resource|request body||
h3. delete
List workflows.
-Arguments:
-
-table(table table-bordered table-condensed).
-|_. Argument |_. Type |_. Description |_. Location |_. Example |
-|limit|integer (default 100)|Maximum number of workflows to return.|query||
-|order|string|Order in which to return matching workflows.|query||
-|filters|array|Conditions for filtering workflows.|query||
+See "common resource list method.":{{site.baseurl}}/api/methods.html#index
h3. update
** A "role" is a subtype of Group that is treated in Workbench as a group of users who have permissions in common (typically an organizational group).
* To change the @owner_uuid@ field, it is necessary to have @can_write@ permission on both the current owner and the new owner.
-h2. Permission links
+h2(#links). Permission links
A link object with
* *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks)
* If User or Group X *can_FOO* Group A, and Group A *can_manage* User B, then X *can_FOO* _everything that User B can_FOO_.
-h2. System user and group
+h2(#system). System user and group
A privileged user account exists for the use by internal Arvados components. This user manages system objects which should not be "owned" by any particular user. The system user uuid is @{siteprefix}-tpzed-000000000000000@.
A authorization token which is not associated with a trusted client may only use the @current@ method to query its own api_client_authorization object. The "untrusted" token is forbidden performing any other operations on API client authorizations, such as listing other authorizations or creating new authorizations.
Authorization tokens which are not issued via the browser login flow (created directly via the API) will not have an associated api client. This means authorization tokens created via the API are always "untrusted".
+
+h2(#scopes). Scopes
+
+Scopes can restrict a token so it may only access certain resources. This is in addition to normal permission checks for the user associated with the token.
+
+Each entry in scopes consists of a @request_method@ and @request_path@, where the @request_method@ is a HTTP method (one of @GET@, @POST@, @PUT@ or @DELETE@) and @request_path@ is the request URI. A given request is permitted if it matches a scopes exactly, or the scope ends with @/@ and the request string is a prefix of the scope.
+
+As a special case, a scope of ["all"] allows all resources.
+
+h3. Scope examples
+
+A scope of @GET /arvados/v1/collections@ permits listing collections.
+
+* Requests with different methods, such as creating a new collection using @POST /arvados/v1/collections@, will be rejected.
+* Requests to access other resources, such as @GET /arvados/v1/groups@, will be rejected.
+* Be aware that requests for specific records, such as @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will also be rejected. This is because the scope @GET /arvados/v1/collections@ does not end in @/@
+
+A scope of @GET /arvados/v1/collections/@ (with @/@ suffix) will permit access to individual collections.
+
+* The request @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will succeed
+* Be aware that requests for listing @GET /arvados/v1/collections@ (no @/@ suffix) will be rejected, because it is not a match with the rule @GET /arvados/v1/collections/@
+* A listing request @GET /arvados/v1/collections/@ will have the trailing @/@ suffix trimmed before the scope check, as a result it will not match the rule @GET /arvados/v1/collections/@.
+
+To allow both listing objects and requesting individual objects, include both in the scope: @["GET /arvados/v1/collections", "GET /arvados/v1/collections/"]@
+
+A narrow scope such as @GET /arvados/v1/collections/962eh-4zz18-xi32mpz2621o8km@ will disallow listing objects as well as disallow requesting any object other than those listed in the scope.
See "Arvados GoDoc":https://godoc.org/git.curoverse.com/arvados.git/sdk/go for detailed documentation.
+In these examples, the site prefix is @aaaaa@.
+
h2. Initialize SDK
<pre>
<pre>
var collection arvados.Collection
- err := api.Delete("collections", "aaaaa-bbbbb-ccccccccccccccc", Dict{}, &collection)
+ err := api.Delete("collections", "aaaaa-4zz18-ccccccccccccccc", Dict{}, &collection)
</pre>
h2. get
<pre>
var collection arvados.Collection
- err := api.Get("collections", "aaaaa-bbbbb-ccccccccccccccc", Dict{}, &collection)
+ err := api.Get("collections", "aaaaa-4zz18-ccccccccccccccc", Dict{}, &collection)
</pre>
h2. list
<pre>
var collection arvados.Collection
- err := api.Update("collections", "aaaaa-bbbbb-ccccccccccccccc", Dict{"collection": Dict{"name": "update example"}}, &collection)
+ err := api.Update("collections", "aaaaa-4zz18-ccccccccccccccc", Dict{"collection": Dict{"name": "update example"}}, &collection)
</pre>
h2. Get current user
title: Examples
...
+In these examples, the site prefix is @aaaaa@.
+
h2. Initialize SDK
<pre>
h2. delete
<pre>
-result = api.collections().delete(uuid="aaaaa-bbbbb-ccccccccccccccc").execute()
+result = api.collections().delete(uuid="aaaaa-4zz18-ccccccccccccccc").execute()
</pre>
h2. get
<pre>
-result = api.collections().get(uuid="aaaaa-bbbbb-ccccccccccccccc").execute()
+result = api.collections().get(uuid="aaaaa-4zz18-ccccccccccccccc").execute()
</pre>
h2. list
h2. update
<pre>
-result = api.collections().update(uuid="aaaaa-bbbbb-ccccccccccccccc", body={"collection": {"name": "update example"}}).execute()
+result = api.collections().update(uuid="aaaaa-4zz18-ccccccccccccccc", body={"collection": {"name": "update example"}}).execute()
</pre>
h2. Get current user
some_user = arv.user.get(uuid: current_user_uuid)
</pre>
-1h2. list
+h2. list
Get a list of objects: