Automating Behance Collection Management with the REST API

Desired Outcome

Build a repeatable, scriptable workflow that can create a Behance collection, bulk‑add projects, update metadata, and verify that every intended project is present—all without manual UI interaction.

Prerequisites

• Behance developer account and an approved application in the Behance Developer Console.
• Client ID and Client Secret for OAuth 2.0.
• At least one existing Behance project ID to add to a collection.
• Python 3.9+ or a shell environment with curl and jq for JSON parsing.
• Secure storage for the access token (e.g., environment variable, key‑vault, or encrypted file).

Authentication – OAuth 2.0

Behance uses OAuth 2.0. The client_credentials grant is simplest for server‑to‑server scripts. The token is short‑lived (~1 hour) and must be refreshed before each operation.

TOKEN=$(curl -s -X POST \
  https://api.behance.net/v2/oauth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  | jq -r '.access_token')
export BEHANCE_TOKEN=$TOKEN

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your credentials. Store $BEHANCE_TOKEN securely; treat it like a password.

Creating a Collection

A collection is created with a POST to /collections. The payload must include a title and an optional array of project IDs. The API caps each request to 50 projects; use pagination for larger batches.

curl -s -X POST \
  https://api.behance.net/v2/collections \
  -H "Authorization: Bearer $BEHANCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Summer Campaign Portfolio",
  "description": "A curated set of summer projects.",
  "public": true,
  "project_ids": [123456, 234567, 345678]
}' \
  | jq

Expected response snippet:

{
  "id": 987654,
  "title": "Summer Campaign Portfolio",
  "description": "A curated set of summer projects.",
  "public": true,
  "project_count": 3
}

Keep the returned id for subsequent updates or deletions.

Adding Projects in Batches

When you have more than 50 projects, send multiple POSTs or use the PUT /collections/{id} endpoint to append projects. Each call can add up to 50 IDs. Example adding 60 projects in two batches:

# First 50 projects
curl -s -X PUT https://api.behance.net/v2/collections/987654 \
  -H "Authorization: Bearer $BEHANCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_ids": ["proj1", "proj2", ... "proj50"]}' | jq

# Remaining 10 projects
curl -s -X PUT https://api.behance.net/v2/collections/987654 \
  -H "Authorization: Bearer $BEHANCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_ids": ["proj51", "proj52", ... "proj60"]}' | jq

Updating Collection Metadata

Change the description or visibility with a PUT to /collections/{id}. Only the fields you send are updated; unspecified fields remain unchanged.

curl -s -X PUT https://api.behance.net/v2/collections/987654 \
  -H "Authorization: Bearer $BEHANCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description for the portfolio."}' | jq

Retrieving and Verifying a Collection

Use GET to confirm the collection’s state. Pagination is required if the collection contains more than 100 projects; the API returns next_page URLs.

curl -s -X GET https://api.behance.net/v2/collections/987654 \
  -H "Authorization: Bearer $BEHANCE_TOKEN" \
  | jq

To iterate over all pages:

PAGE_URL="https://api.behance.net/v2/collections/987654"
while [ -n "$PAGE_URL" ]; do
  RESPONSE=$(curl -s -X GET "$PAGE_URL" \
    -H "Authorization: Bearer $BEHANCE_TOKEN")
  echo "$RESPONSE" | jq
  PAGE_URL=$(echo "$RESPONSE" | jq -r '.next_page // empty')
done

Error Handling

• 401 Unauthorized – Refresh the OAuth token.
• 429 Too Many Requests – Implement exponential back‑off (e.g., wait 2 s, then double each retry).
• 400 Bad Request – Validate project IDs and payload structure before sending.

Sample error response:

{
  "error": "invalid_project_id",
  "message": "Project ID 999999 does not exist."
}

Rollback – Deleting a Collection

If a collection is created incorrectly, delete it with a DELETE request. This operation is irreversible; confirm the id before proceeding.

curl -s -X DELETE https://api.behance.net/v2/collections/987654 \
  -H "Authorization: Bearer $BEHANCE_TOKEN"

Limitations and Practical Checks

• The client_credentials grant does not allow user‑specific actions; if you need to act on a particular user’s behalf, use the authorization_code flow.
• Rate limits differ by account tier; monitor the X-RateLimit-Remaining header and throttle if it approaches zero.
• Public and private collections behave identically for CRUD, but visibility changes may affect search indexing; verify with a GET after updating public flag.
• Always log the response status code and body to a file for audit and debugging.

Putting It All Together – Sample Script

The following Bash snippet ties the steps into a single workflow. It creates a collection, adds 120 projects (3 batches), updates the description, and verifies the final project count.

#!/usr/bin/env bash
set -euo pipefail

# 1. Obtain token
TOKEN=$(curl -s -X POST \
  https://api.behance.net/v2/oauth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  | jq -r '.access_token')

# 2. Create collection
COL_ID=$(curl -s -X POST https://api.behance.net/v2/collections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bulk Portfolio", "public": true}' \
  | jq -r '.id')

# 3. Add projects in batches of 50
PROJECTS=( $(seq 1 120 | sed 's/^/proj/') )
for BATCH in 0 1 2; do
  START=$((BATCH * 50))
  END=$((START + 49))
  BATCH_IDS=$(printf '%s,' "${PROJECTS[@]:$START:50}" | sed 's/,$//')
  curl -s -X PUT https://api.behance.net/v2/collections/$COL_ID \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"project_ids\":[$BATCH_IDS]}"
  sleep 1
done

# 4. Update description
curl -s -X PUT https://api.behance.net/v2/collections/$COL_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Finalized bulk collection."}'

# 5. Verify count
COUNT=$(curl -s -X GET https://api.behance.net/v2/collections/$COL_ID \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.project_count')
echo "Collection $COL_ID contains $COUNT projects."

Replace placeholder values with real IDs. Run the script in a test environment first to ensure the API behaves as expected.

Conclusion

By combining OAuth 2.0 authentication, CRUD endpoints, and pagination handling, designers can automate the organization of their Behance portfolio. The workflow above illustrates a robust, repeatable process that can be integrated into CI/CD pipelines, content management systems, or personal automation scripts.