Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

PUT /library/`{library_id}`/refer

Edits one or more existing domain referrers (refer_ids) in a single transactional call (mass edit). In one request it can:

rename the domain (hostname) in place on the kept rows,
change the scope (library ↔ folder),
change the set of linked folders (folder_ids add/remove — the backend computes the diff vs the current state),
change the type (ALLOW ↔ BLOCK).

All matching rows are edited atomically (Sequelize transaction); on success the affected library and folders are queued for edge (KVS) synchronization and a single audit log with the resulting diff is emitted.

Conflict on rename returns 400 if another active row already uses the target hostname in the target scope; a missing refer_id returns 404.

📘
Authorization
Requires a valid API token in the Authorization header (without Bearer prefix). The library is resolved by the token's user_id and the library_id must belong to the authenticated user.

HTTP Method & Path

PUT /library/{library_id}/refer

Base URL: https://api-v2.pandavideo.com.br

Authentication Requirements

Header	Value
`Authorization`	Your Panda API token (no `Bearer` prefix)

Path Parameters

Name	Type	Required	Description
`library_id`	string (uuid v4)	yes	Library ID owned by the authenticated user

Request Body

Content-Type: application/json

Body Parameters

Name	Type	Required	Description
`refer_ids`	string[] (uuid)	yes	One or more existing referrer IDs to edit in this batch
`hostname`	string	yes	New domain hostname (applied in place to the kept rows)
`type`	string	yes	`ALLOW` or `BLOCK`
`scope`	string	yes	`library` or `folder` — target scope after edit
`folder_ids`	string[] (uuid)	conditional	Required when `scope === "folder"`. Full target set — backend computes diff (add/remove) vs current state

Example — rename a domain and move it to library scope:

{
  "refer_ids": ["789e4567-e89b-12d3-a456-426614174999"],
  "hostname": "*.novo-cliente.com",
  "type": "ALLOW",
  "scope": "library"
}

Example — set the folders a domain applies to (add/remove diff):

{
  "refer_ids": [
    "789e4567-e89b-12d3-a456-426614174999",
    "999e4567-e89b-12d3-a456-426614174000"
  ],
  "hostname": "*.cliente.com",
  "type": "BLOCK",
  "scope": "folder",
  "folder_ids": [
    "22222222-2222-4222-8222-222222222222",
    "33333333-3333-4333-8333-333333333333"
  ]
}

Response

Success Response (200)

{
  "message": "Domain updated successfully",
  "hostname": "new.example.com",
  "type": "ALLOW",
  "scope": "folder",
  "renamed": true,
  "folders_added": ["f0000000-0000-4000-8000-000000000003"],
  "folders_removed": ["f0000000-0000-4000-8000-000000000002"],
  "refers": [
    {
      "id": "c3333333-3333-4333-8333-333333333333",
      "url": "new.example.com",
      "type": "ALLOW",
      "status": "pending",
      "origin": { "type": "folder", "id": "f0000000-0000-4000-8000-000000000003" }
    },
    {
      "id": "a1111111-1111-4111-8111-111111111111",
      "url": "new.example.com",
      "type": "ALLOW",
      "status": "active",
      "origin": { "type": "folder", "id": "f0000000-0000-4000-8000-000000000001" }
    }
  ]
}

Response Schema

Field	Type	Description
`message`	string	Success message
`hostname`	string	Final hostname applied to all edited rows
`type`	string	Final type — `ALLOW` or `BLOCK`
`scope`	string	Final scope — `library` or `folder`
`renamed`	boolean	`true` when the `hostname` differed from the previous value on any kept row
`folders_added`	string[] (uuid)	Folder IDs newly linked by this call (diff result)
`folders_removed`	string[] (uuid)	Folder IDs unlinked by this call (diff result)
`refers`	object[]	Kept/active rows after the edit
`refers[].id`	string (uuid)	Refer ID
`refers[].url`	string	Hostname (mirrors the top-level `hostname`)
`refers[].type`	string	`ALLOW` or `BLOCK`
`refers[].status`	string	`active`, `pending`, `inactive`, `deleting`, or `turning_inactive`
`refers[].origin`	object	Scope this row applies to
`refers[].origin.type`	string	`library` or `folder`
`refers[].origin.id`	string (uuid)	The library or folder ID this row applies to

Error Responses

Status	When
`400`	Rename conflict — another active row already uses the target `hostname` in the target scope. Or validation error (missing field, bad UUID, invalid enum)
`404`	One of the supplied `refer_ids` does not exist
`500`	Internal error (database failure, transaction rollback, etc.)

Example Usage

cURL — rename a domain and move it to library scope

curl -X PUT \
  -H "Authorization: $PANDA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refer_ids": ["789e4567-e89b-12d3-a456-426614174999"],
    "hostname": "*.novo-cliente.com",
    "type": "ALLOW",
    "scope": "library"
  }' \
  https://api-v2.pandavideo.com.br/library/123e4567-e89b-12d3-a456-426614174000/refer

cURL — set the folders a domain applies to (add/remove diff)

curl -X PUT \
  -H "Authorization: $PANDA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refer_ids": [
      "789e4567-e89b-12d3-a456-426614174999",
      "999e4567-e89b-12d3-a456-426614174000"
    ],
    "hostname": "*.cliente.com",
    "type": "BLOCK",
    "scope": "folder",
    "folder_ids": [
      "22222222-2222-4222-8222-222222222222",
      "33333333-3333-4333-8333-333333333333"
    ]
  }' \
  https://api-v2.pandavideo.com.br/library/123e4567-e89b-12d3-a456-426614174000/refer

PUT /library/{library_id}/refer

Authorization

HTTP Method & Path

Authentication Requirements

Path Parameters

Request Body

Body Parameters

Response

Success Response (200)

Response Schema

Error Responses

Example Usage

cURL — rename a domain and move it to library scope

cURL — set the folders a domain applies to (add/remove diff)

200Domain referrers edited successfully

400Bad request - Invalid input parameters

404Not found - Resource does not exist

500Internal server error

PUT /library/`{library_id}`/refer