# Connection API Reference

OpenAPI source: https://api.are.na/v3/openapi.json

## PUT /v3/connections/{id}

- Label: Update a connection
- Docs: https://www.are.na/developers/explore/connection/put-connection
- Markdown: https://www.are.na/developers/explore/connection/put-connection.md
- Requires resource id: yes
- Response content type: application/json

Updates a connection's metadata. Uses merge semantics: new keys are added,
existing keys are updated, keys set to null are removed.

**Authentication required.**

Request body schema:
```json
{
  "type": "object",
  "required": [],
  "properties": {
    "metadata": {
      "type": "object",
      "description": "Arbitrary key-value pairs to set on an entity. Uses merge semantics:\nnew keys are added, existing keys are updated, keys set to null are removed.\nKeys must be alphanumeric/underscore, max 40 characters.\nValues must be scalars (string, number, boolean) or null (to delete). Max 50 keys, 32KB total.\n",
      "required": [],
      "properties": {},
      "additionalProperties": {
        "type": "oneOf",
        "variants": [
          {
            "type": "string",
            "nullable": false
          },
          {
            "type": "number",
            "nullable": false
          },
          {
            "type": "boolean",
            "nullable": false
          },
          {
            "type": "unknown",
            "nullable": true
          }
        ]
      },
      "refName": "MetadataInput"
    }
  }
}
```

Response schema:
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "nullable": false,
      "description": "Unique identifier for the connection",
      "example": 98765
    },
    "position": {
      "type": "integer",
      "nullable": false,
      "description": "Position of the item within the channel (1-indexed)",
      "example": 1
    },
    "pinned": {
      "type": "boolean",
      "nullable": false,
      "description": "Whether the item is pinned",
      "example": false
    },
    "metadata": {
      "type": "oneOf",
      "description": "Custom key-value metadata",
      "variants": [
        {
          "type": "object",
          "description": "Arbitrary key-value pairs stored on an entity.\nKeys are alphanumeric/underscore, max 40 characters.\nValues are scalars (string, number, boolean). Max 50 keys, 32KB total.\n",
          "required": [],
          "properties": {},
          "additionalProperties": {
            "type": "oneOf",
            "variants": [
              {
                "type": "string",
                "nullable": false
              },
              {
                "type": "number",
                "nullable": false
              },
              {
                "type": "boolean",
                "nullable": false
              }
            ]
          },
          "refName": "Metadata"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "connected_at": {
      "type": "string",
      "nullable": false,
      "description": "When the item was connected",
      "format": "date-time",
      "example": "2023-01-15T10:30:00Z"
    },
    "connected_by": {
      "type": "oneOf",
      "description": "User who created this connection",
      "variants": [
        {
          "type": "object",
          "description": "Embedded user representation (used when user is nested in other resources)",
          "required": [
            "id",
            "type",
            "name",
            "slug",
            "avatar",
            "initials"
          ],
          "properties": {
            "id": {
              "type": "integer",
              "nullable": false,
              "description": "Unique identifier for the user",
              "example": 12345
            },
            "type": {
              "type": "string",
              "nullable": false,
              "description": "User type",
              "enum": [
                "User"
              ],
              "example": "User"
            },
            "name": {
              "type": "string",
              "nullable": false,
              "description": "User's display name",
              "example": "John Doe"
            },
            "slug": {
              "type": "string",
              "nullable": false,
              "description": "URL-safe identifier (use this in API paths)",
              "example": "john-doe"
            },
            "avatar": {
              "type": "string",
              "nullable": true,
              "description": "URL to user's avatar image",
              "format": "uri",
              "example": "https://d2w9rnfcy7mm78.cloudfront.net/12345/avatar.jpg"
            },
            "initials": {
              "type": "string",
              "nullable": false,
              "description": "User's initials",
              "example": "JD"
            }
          },
          "refName": "EmbeddedUser"
        },
        {
          "type": "unknown",
          "nullable": true
        }
      ]
    },
    "can": {
      "type": "object",
      "description": "Actions the current user can perform on this connection",
      "required": [
        "remove"
      ],
      "properties": {
        "remove": {
          "type": "boolean",
          "nullable": false,
          "description": "Whether the user can remove this connection",
          "example": true
        }
      },
      "refName": "ConnectionAbilities"
    },
    "_links": {
      "type": "object",
      "description": "HATEOAS links for navigation and discovery.\nFollows HAL (Hypertext Application Language) format where link relationships \nare expressed as object keys (e.g., \"self\", \"user\", \"channels\").\n",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "type": "object",
          "description": "A hypermedia link containing the URL of a linked resource.\nThe relationship type is expressed by the key in the parent _links object.\n",
          "required": [
            "href"
          ],
          "properties": {
            "href": {
              "type": "string",
              "nullable": false,
              "description": "The URL of the linked resource",
              "format": "uri",
              "example": "https://api.are.na/v3/blocks/12345"
            }
          },
          "refName": "Link"
        }
      },
      "additionalProperties": {
        "type": "object",
        "description": "A hypermedia link containing the URL of a linked resource.\nThe relationship type is expressed by the key in the parent _links object.\n",
        "required": [
          "href"
        ],
        "properties": {
          "href": {
            "type": "string",
            "nullable": false,
            "description": "The URL of the linked resource",
            "format": "uri",
            "example": "https://api.are.na/v3/blocks/12345"
          }
        },
        "refName": "Link"
      },
      "refName": "Links"
    }
  },
  "required": [
    "id",
    "position",
    "pinned",
    "connected_at",
    "connected_by",
    "can",
    "_links"
  ],
  "description": "Full connection resource with abilities and links.\nUsed for GET /v3/connections/:id\n",
  "refName": "Connection"
}
```