LinkedIn Page Publisher

intent

publish content to a LinkedIn Company Page through LinkedIn's versioned REST API (/rest/posts). use this when the user wants to post to LinkedIn, publish to a Company Page, automate LinkedIn content, cross-post from another system, build a LinkedIn publishing bot or scheduler, or upload images or videos to LinkedIn programmatically. also use it when the user mentions errors from the LinkedIn Posts API, w_organization_social scope, urn:li:organization URNs, UGC posts, or /rest/images and /rest/videos endpoints. the skill ships a Python CLI (scripts/publish.py) that works as both a standalone tool and an importable library, plus a one-time OAuth helper (scripts/get_token.py) to obtain the initial access token.

inputs

Environment variables (required unless noted):

External connections:

• LinkedIn Developer Platform (OAuth 2.0, Community Management API): requires app creation and w_organization_social scope approval. the authenticating user must be an admin of the Company Page (employee status is not sufficient). setup walkthrough in references/setup.md.

CLI subcommands:

• python scripts/publish.py text (text-only post)
• python scripts/publish.py image (single image with alt text)
• python scripts/publish.py multi-image (2-20 image carousel)
• python scripts/publish.py video (video with optional title)
• python scripts/publish.py article (article link preview)

all subcommands accept --text (post commentary, up to 3,000 characters) and --dry-run (prints request body without calling the API).

procedure

step 1: obtain access token (one-time setup). input: none (user runs script). run python scripts/get_token.py. this launches a local OAuth 2.0 flow. the script opens a browser, prompts the user to log in and approve w_organization_social scope on the LinkedIn Developer app, then captures the auth code. the script saves the access token and refresh token to a secure location and exports them as environment variables. output: LINKEDIN_ACCESS_TOKEN and LINKEDIN_REFRESH_TOKEN ready to use.

step 2: set organization ID. input: user's LinkedIn Company Page URL. user navigates to https://www.linkedin.com/company/<slug>/admin/ and locates the numeric ID in the browser URL bar. user sets LINKEDIN_ORG_ID environment variable to this number (e.g. export LINKEDIN_ORG_ID=5515715). output: LINKEDIN_ORG_ID environment variable set.

step 3: choose content type and prepare inputs. input: user's post content (text, image, video, or article URL). user selects the appropriate subcommand based on the content type:

• text-only: runs python scripts/publish.py text --text "..."
• single image: prepares image file path and alt text, runs python scripts/publish.py image path/to/photo.jpg --text "..." --alt "..."
• multi-image carousel: prepares 2-20 image file paths and one alt text per image (in order), runs python scripts/publish.py multi-image img1.jpg img2.jpg ... --text "..." --alt "alt1" "alt2" ...
• video: prepares video file path and optional title, runs python scripts/publish.py video path/to/demo.mp4 --text "..." --title "..."
• article: provides article URL, runs python scripts/publish.py article https://example.com/post --text "..." output: validated input arguments ready for API call.

step 4: validate and optionally dry-run. input: prepared arguments from step 3. the CLI validates inputs locally before calling the API:

• text length ≤ 3,000 characters (returns HTTP 422 if exceeded).
• alt text count matches image count for multi-image posts.
• image/video file paths exist and are readable.
• alt text is non-empty (required for accessibility and ranking). user optionally adds --dry-run flag to print the request body without calling LinkedIn. output: validated inputs, optionally printed request body for inspection.

step 5: register media with LinkedIn (for image, video, multi-image, or article). input: validated image, video, or article inputs. the library calls POST /rest/images?action=initializeUpload (images) or POST /rest/videos?action=initializeUpload (videos). LinkedIn responds with an upload URL (or multiple URLs for multipart video uploads) and a pre-assigned URN (e.g. urn:li:image:... or urn:li:video:...). output: upload URL(s) and media URN. for multi-image posts, repeat this step for each image.

step 6: upload binary media to LinkedIn (for image, video, or multi-image). input: upload URL(s) from step 5, binary file contents. the library PUTs the binary bytes to the returned upload URL(s). these URLs are pre-signed; no auth header is needed.

• single-part upload: for files ≤ 200 MB, one PUT call per file.
• multipart upload: for files > 200 MB, multiple PUT calls with part numbers. the library calculates ETags for each part. after all PUTs complete, for multipart uploads, the library calls POST /rest/videos/{urn}?action=finalizeUpload with the ETags to signal to LinkedIn that the upload is complete. output: upload acknowledged by LinkedIn. for videos, the asset enters asynchronous processing.

step 7: poll video status (videos only). input: video URN from step 5. for video posts, the library polls GET /rest/videos/{urn} every 2-5 seconds until status == AVAILABLE. this prevents posting with a broken video player (the post would show if you create it before processing finishes). the poll timeout is 5 minutes; if the video is not AVAILABLE by then, the library raises an error with the LinkedIn response body. output: video URN confirmed as AVAILABLE and ready to reference in post.

step 8: create the post with media URN(s). input: post text, media URN(s) from steps 5-7, optional article metadata. the library calls POST /rest/posts with the post payload:

• for text-only: { "author": "urn:li:organization:...", "commentary": "..." }
• for image(s): { "author": "urn:li:organization:...", "commentary": "...", "content": { "media": { "id": "urn:li:image:..." } } } (multi-image uses media array)
• for video: same structure with video URN
• for article: { "author": "urn:li:organization:...", "commentary": "...", "content": { "article": { "source": "..." } } } output: post URN (e.g. urn:li:share:7045020441609936898) on success.

step 9: return result to user. input: post URN from step 8. the library returns the post URN. the CLI prints it to stdout. if the user ran with --dry-run, step 8 never executes and the request body is printed instead. output: post URN or error message with LinkedIn's response body (for debugging).

decision points

if the user has an existing access token but it's expired (401 Unauthorized from LinkedIn): the library checks the token's exp claim. if expired, the library attempts to refresh using the stored refresh token by calling LinkedIn's token endpoint. if a refresh token is not available, the flow fails and the user must re-run scripts/get_token.py. if the refresh succeeds, the new access token is used for the post.

if the user is not an admin of the Company Page: LinkedIn returns HTTP 403 Forbidden with serviceErrorCode "NOT_AUTHORIZED". the error message is misleading (says "unauthorized" not "not an admin"). direct the user to check their admin status in the Company Page settings, not to check their token.

if alt text count does not match image count (multi-image posts): the CLI validates this locally before calling the API and errors out with a clear message. the user must provide exactly one --alt per image in order.

if a single-image or multi-image file is not found or not readable: the CLI exits with a file-not-found error before calling the API. this is cheaper than discovering it mid-upload.

if the post text exceeds 3,000 characters: the CLI validates this locally and errors out before calling the API. LinkedIn returns HTTP 422 if the text is too long.

if a video file is ≤ 200 MB (single-part upload path): the library auto-detects file size and uses a single PUT call, then polls for AVAILABLE status.

if a video file is > 200 MB (multipart upload path): the library chunks the file, PUTs each chunk with a part number, collects ETags, then calls finalizeUpload to signal completion. polling for AVAILABLE still occurs.

if a video does not reach AVAILABLE status within 5 minutes: the library raises an error with the last-known video status and the LinkedIn response body. the user must retry or check the video file for corruption.

if the article URL's OpenGraph metadata is missing or malformed: LinkedIn scrapes the URL server-side. if OG tags are absent, the preview card will be blank or minimal. this is a site issue, not an API issue. the post still succeeds; the preview quality is not the API's responsibility.

if the user provides --dry-run: all validation steps 1-4 execute, but step 8 (the actual API call) is skipped. the CLI prints the request payload to stdout for inspection. this is useful for testing without hitting the API quota.

if rate limit is hit (100 calls/day/member): LinkedIn returns HTTP 429 Too Many Requests. the library does not retry (the user owns throttling logic). the error message is clear. if the user is building a scheduler, they must space posts or use a queue.

output contract

on success (all subcommands):

• post URN string (e.g. urn:li:share:7045020441609936898) printed to stdout.
• exit code: 0.
• for image/video/multi-image posts, media URN(s) also logged for verification.

on failure:

• error message including the LinkedIn serviceErrorCode, the HTTP status code, and the full response body.
• exit code: non-zero.
• error is raised (not swallowed). the caller must decide whether to retry, log, or escalate.

if --dry-run is used:

• request body (JSON) printed to stdout.
• no API call is made.
• exit code: 0.

library usage (from Python):

• post_text(client, text: str) -> str returns post URN.
• post_image(client, image_path: str, text: str, alt: str) -> str returns post URN.
• post_video(client, video_path: str, text: str, title: str = None) -> str returns post URN (after polling for AVAILABLE).
• post_article(client, article_url: str, text: str) -> str returns post URN.
• post_multi_image(client, image_paths: list[str], text: str, alts: list[str]) -> str returns post URN.
• all functions raise on error; do not catch exceptions silently.

outcome signal

user knows the skill worked when:

• the CLI printed a post URN to stdout and exited with code 0.
• the post is immediately visible on the Company Page's feed (text and link posts appear instantly; images and videos appear within seconds once processing finishes).
• for video posts, the video player is functional (not grayed out or showing a loading spinner) , this confirms the polling in step 7 worked.
• --dry-run mode printed a valid JSON request body that the user can inspect before committing.

user knows something failed when:

• the CLI exited with a non-zero code and printed an error message.
• the error message includes a LinkedIn serviceErrorCode (e.g. "NOT_AUTHORIZED", "INVALID_SCOPE"). cross-reference this in references/troubleshooting.md.
• for 401 errors: token is expired or invalid. retry with a refreshed token or re-run scripts/get_token.py.
• for 403 errors: user is not an admin of the Company Page. check admin status.
• for 422 errors: post text is too long or required fields are missing. check the request body (use --dry-run to inspect).
• for 429 errors: rate limit hit. space posts further apart or use a queue.
• no post appears on the feed within 30 seconds (and no error was returned). check network connectivity, then contact LinkedIn support with the request timestamp and org ID.