---
layout: default
navsection: api
navmenu: API Methods
title: "links"

...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/links@

Object type: @o0j2j@

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 "Common resource fields":{{site.baseurl}}/api/resources.html:

table(table table-bordered table-condensed).
|_. Attribute|_. Type|_. Description|
|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.  May be used in queries using "subproperty filters":{{site.baseurl}}/api/methods.html#subpropertyfilters|

h2. Link classes

Some classes are pre-defined by convention and have standard meanings attached to names.

h3. permission

See "permission links":{{site.baseurl}}/api/permission-model.html#links section of the permission model.

h3. tag

A **tag** link describes an object using an unparsed plain text string. Tags can be used to annotate objects that are not editable, like collections and objects shared as read-only.

table(table table-bordered table-condensed).
|_. tail_type→head_type|_. name→head_uuid {properties}|
|→Collection           | _tag name_ → _collection uuid_|
|→Job                  | _tag name_ → _job uuid_|

h2. Methods

See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.

Required arguments are displayed in %{background:#ccffcc}green%.

h3. create

Create a new Link.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
|link|object||query||

h3. delete

Delete an existing Link.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||

h3. get

Gets a Link's metadata by UUID.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||

h3. list

List links.

See "common resource list method.":{{site.baseurl}}/api/methods.html#index

h3. update

Update attributes of an existing Link.

Arguments:

table(table table-bordered table-condensed).
|_. Argument |_. Type |_. Description |_. Location |_. Example |
{background:#ccffcc}.|uuid|string|The UUID of the Link in question.|path||
|link|object||query||