NAME

Webservice::Overleaf::API - Perl client helpers for Overleaf import, Git, and experimental project operations

SYNOPSIS

use Webservice::Overleaf::API;

my $ol = Webservice::Overleaf::API->new;

# Official Open in Overleaf interface
my $url = $ol->open_uri(
    uri           => 'https://example.org/paper.zip',
    engine        => 'lualatex',
    main_document => 'main.tex',
);

# Official Git bridge
say $ol->git_url('0123456789abcdef');
$ol->git_clone('0123456789abcdef', 'paper');

# Undocumented web application interface -- opt in explicitly.
my $web = Webservice::Overleaf::API->new(
    experimental => 1,
    session      => $ENV{OVERLEAF_SESSION},
);

for my $project ($web->projects->all) {
    say $project->name;
}

my $compile = $web->compile(
    '0123456789abcdef',
    resource_path => 'main.tex',
);
$web->download_pdf('0123456789abcdef', compile => $compile, to => 'paper.pdf');

DESCRIPTION

This distribution deliberately separates supported Overleaf integration surfaces from browser-session interfaces that Overleaf does not document as a public API.

The supported side covers the Open in Overleaf import interface and the Overleaf Git bridge. The experimental side uses the same project HTML and compile/download endpoints used by the web application. Those endpoints may change without notice and therefore require experimental => 1.

Dispatch::Fu is used for both public operation dispatch and HTTP response classification. Util::H2O::More is used for compact construction and for objectifying returned project and compile data.

CONSTRUCTOR

new

my $ol = Webservice::Overleaf::API->new(
    base_url     => 'https://www.overleaf.com',
    git_base_url => 'https://git.overleaf.com',
    experimental => 0,
    session      => $ENV{OVERLEAF_SESSION},
    cookie_name  => 'overleaf_session2',
    ua           => $http_tiny_compatible_object,
    git_runner   => sub { ... },
);

ua and git_runner are injectable specifically so callers and the test suite can isolate all network and process execution.

OFFICIAL OVERLEAF INTERFACES

open_uri

Builds an Open in Overleaf URL. Accepts uri or uris, optional name or names, and the documented engine, main_document, and visual_editor features.

open_data

Base64-encodes content into a data URI and returns an Open in Overleaf URL. The default MIME type is application/x-tex; use application/zip for a ZIP project.

open_snippet_form

Returns an object describing a POST form to /docs with a raw snip field. This is useful when embedding an Open in Overleaf button in an application.

project_url

Returns the normal browser/editor URL for a project.

git_url

Returns the Git bridge URL for a project.

git_clone, git_pull, git_push, git_remote_add

Run Git using list-form system, avoiding shell interpolation. Authentication is intentionally left to Git's credential mechanism; this module does not put Overleaf Git authentication tokens on the command line or in remote URLs.

AUTHENTICATION

There are two distinct authentication paths because this module uses two separate Overleaf integration surfaces.

Official Git bridge

Git operations use the official Overleaf Git bridge. For Overleaf Cloud, create a Git authentication token in the Overleaf account settings under Git Integration and let Git use that token as the password for the git user. The same token can be used for the projects accessible to that Overleaf account.

This module deliberately leaves credential storage to Git. Use a Git credential helper rather than embedding the token in a remote URL or passing it on a command line.

Experimental browser-session operations

The experimental project-listing, ZIP, compile, PDF, and compile-output methods use the same authenticated browser session as the Overleaf web application. At present the practical authentication method is to copy the value of the overleaf_session2 cookie from a browser in which you are already logged in.

For Firefox:

Log into https://www.overleaf.com/ normally.
Open Developer Tools with F12 and select Storage.
Open Cookies, select https://www.overleaf.com, and find overleaf_session2.
Copy only the cookie's Value, not the literal overleaf_session2= prefix.

Chrome-family browsers expose the same cookie under Developer Tools, Application, Storage, Cookies.

The copied value can be supplied directly:

my $ol = Webservice::Overleaf::API->new(
    experimental => 1,
    session      => $session_value,
);

or through the environment:

$ENV{OVERLEAF_SESSION} = $session_value;

my $ol = Webservice::Overleaf::API->new(
    experimental => 1,
);

Treat overleaf_session2 like a password. It grants access as the logged-in Overleaf user and must not be committed, logged, pasted into bug reports, or otherwise disclosed.

Session lifetime

As of the Overleaf Cookie Policy last modified 5 August 2026, overleaf_session2 is an authentication cookie with a documented retention period of 5 days. A copied session value should therefore be treated as a short-lived credential and refreshed from the browser when authentication stops working.

The five-day retention period is not a guarantee that a particular copied session will remain valid for exactly five days. Logging out, revocation, rotation, security changes, or other server-side invalidation may make it stop working earlier.

See https://www.overleaf.com/legal for Overleaf's current cookie policy.

EXPERIMENTAL WEB APPLICATION INTERFACE

These methods require both experimental => 1 and an Overleaf session cookie. OVERLEAF_SESSION is used when session is not passed directly. See "AUTHENTICATION" for the current browser-cookie procedure and session lifetime. Treat this cookie like a password and do not commit or log it.

bootstrap

Fetches the project page and obtains the CSRF token required by state-changing web application requests.

projects

Returns the current non-archived, non-trashed projects as a Util::H2O::More objectified array. It understands the current prefetched-project metadata and older metadata shapes used by older/self-hosted Overleaf releases.

project_zip

Downloads a project ZIP. With to => $filename it writes the bytes to that file; otherwise it returns the bytes.

compile

Compiles a project remotely and returns an object containing status, pdf_url, compile_group, clsi_server_id, and output_files.

An optional resource_path requests that a particular TeX file be treated as the root document for the compile.

download_pdf

Compiles and downloads output.pdf, or accepts a previous compile result via compile => $result. With to => $filename it writes the PDF.

download_output

$ol->download_output($compile, 'output.log', to => 'output.log');

Downloads a named compile artifact from a previous compile result.

COMMAND-LINE CLIENT

The distribution includes overleaf, a command-line companion implemented as a modulino in bin/overleaf. It uses Util::H2O::More::Getopt2h2o for option handling and Dispatch::Fu for command routing.

The CLI exposes the same two broad integration surfaces as the module:

The documented Open in Overleaf interface and Git bridge.
The explicitly opt-in browser-session interface used for project listing, project ZIP download, remote compilation, PDF retrieval, and build artifacts.

For day-to-day work, a practical session-based setup is:

# Copy only the value of the overleaf_session2 browser cookie.
printf '%s\n' 'PASTE_COOKIE_VALUE_HERE' > ~/.ol-session.txt
chmod 600 ~/.ol-session.txt

SESSION=~/.ol-session.txt

overleaf --experimental \
    --session-file "$SESSION" \
    bootstrap

A successful bootstrap prints:

authenticated

List projects and choose the project ID you want to work with:

overleaf --experimental \
    --session-file "$SESSION" \
    projects

ID=0123456789abcdef

A project ZIP is the easiest way to inspect the source tree:

overleaf --experimental \
    --session-file "$SESSION" \
    --output project.zip \
    zip "$ID"

unzip -l project.zip
unzip -l project.zip | grep -Ei '\.tex$'

The compile command is different: it lists build artifacts, not source files. It prints the compilation status, PDF URL, and generated files such as output.log, output.bbl, output.chktex, and output.pdf:

overleaf --experimental \
    --session-file "$SESSION" \
    compile "$ID"

A useful way to discover the root TeX document used by Overleaf is to retrieve the compilation log and inspect its initial **filename.tex line:

overleaf --experimental \
    --session-file "$SESSION" \
    --output output.log \
    output "$ID" output.log

grep -m1 '^\*\*[^*]' output.log

Once the root is known, it can be requested explicitly:

ROOT_TEX=user_guide.tex

overleaf --experimental \
    --session-file "$SESSION" \
    --resource-path "$ROOT_TEX" \
    compile "$ID"

Download the resulting PDF:

overleaf --experimental \
    --session-file "$SESSION" \
    --resource-path "$ROOT_TEX" \
    --output document.pdf \
    pdf "$ID"

On a Linux desktop:

xdg-open document.pdf >/dev/null 2>&1 &

From MSYS2/Git Bash on Windows:

start document.pdf

The Git bridge is separate from the browser-session credential. Git uses Overleaf's token-based Git authentication and its normal credential handling. For a project with Git integration enabled:

overleaf git-url "$ID"
overleaf clone "$ID" my-paper
overleaf pull my-paper

After editing and committing locally, a clone whose branch already tracks the Overleaf remote can normally be pushed with:

overleaf push my-paper

For an existing local Git repository, add Overleaf as a named remote:

overleaf remote-add . "$ID" overleaf
git remote -v

Overleaf's Git bridge represents a single linear project history and currently uses the remote master branch. When connecting an unrelated existing repository, consult Overleaf's Git integration documentation before the first pull or push.

overleaf --help contains the complete command reference and a more detailed start-to-finish walkthrough.

DISPATCH INTERFACE

call

my $projects = $ol->call('projects');
my $git_url  = $ol->call('git_url', $project_id);

Uses Dispatch::Fu to route a static operation name to the corresponding method. Unsupported names throw an exception.

TESTING

The distribution's tests make no live Overleaf requests. The HTTP client and Git runner are injected and mocked so request methods, URLs, headers, compile bodies, error handling, binary downloads, and dispatch behavior are exercised deterministically.

COMPATIBILITY NOTES

Overleaf documents the Open in Overleaf interface and Git integration. It does not document the ordinary project web application's browser endpoints as a stable public API. The experimental implementation is informed by observable web-client behavior and by the open-source olcli project, which tracks these endpoint changes in practice.

AUTHOR

Brett Estrade <oodler@cpan.org>

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Webservice::Overleaf::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Webservice::Overleaf::API

CPAN shell

perl -MCPAN -e shell
install Webservice::Overleaf::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)