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.
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. 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.
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.
SEE ALSO
Dispatch::Fu, Util::H2O::More, HTTP::Tiny, https://www.overleaf.com/devs, https://www.overleaf.com/learn/how-to/Git_integration, https://github.com/aloth/olcli
AUTHOR
Brett Estrade <oodler@cpan.org>
LICENSE AND COPYRIGHT
Copyright 2026 Brett Estrade.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.