[vdusek]

Adds three methods to ActorClient and ActorClientAsync for working with Server Actors:

• server_request() sends an HTTP request to the Actor's server without looking up its URL or attaching the token by hand.
• get_server_url() returns the server URL (the Actor's standbyUrl), for calling the server with another HTTP client.
• get_server_openapi_spec() returns the server's OpenAPI specification (the web server schema from the Actor's definition), for generating such a client.

actor = client.actor('username/actor-name')
response = actor.server_request('/search', params={'q': 'apify'})
spec = actor.get_server_openapi_spec()

server_request follows the CLI RFC (apify/apify-cli#1299):

• The caller passes a path. The host always comes from the Actor's standbyUrl, and the token goes in the Authorization header, which the platform strips before forwarding.
• Request bodies are uncompressed by default, and compression opts in. The timeout defaults to long to cover a cold start.
• Error statuses raise ApifyApiError, and 5xx/429 are retried like API calls.

get_server_openapi_spec reads the spec from the build the Actor runs in Server mode: actorStandby.build (a tag or a build number), or latest if none is set. It returns None when the build has no web server schema. The schema field comes from apify/apify-docs#3115.

To support compression per request, HttpClient.call and HttpClientAsync.call take a new compression argument. A custom HTTP client that overrides call must accept it.

Also fixes the docstring sync script turning ApifyClientError into a nonexistent ApifyClientAsyncError, and adds a Server Actors concepts page.

Closes: #973

✍️ Drafted by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.05263% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.55%. Comparing base (d1bc83a) to head (0addab8).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/apify_client/_resource_clients/actor.py	95.83%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1153   +/-   ##
=======================================
  Coverage   95.55%   95.55%           
=======================================
  Files          61       61           
  Lines        6004     6077   +73     
=======================================
+ Hits         5737     5807   +70     
- Misses        267      270    +3     

Flag	Coverage Δ
integration	89.74% <18.42%> (-1.08%)	⬇️
unit	90.04% <96.05%> (+0.20%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vdusek]

I'm not sure about the name server_request 😄, but couldn't come up with anything better... Happy to hear your ideas.

[Pijukatel]

I am still not sure about the ideal way to support server actors. Those can be of very different categories:

1. Full app for browser
2. Simple one endpoint API
3. Complex API with many endpoints and full OpenAPI specification
4. ...?

I think this change fits very well the 2. usecase, while its utility drops for the others.

What will be the natural way to work with usecase 3? I guess it could be actually generating that actor-server specific API client and using that. The only thing needed for that is the proper URL

So as mentioned in the Slack discussion in the issue description, I would probably also add these 2 methods:

• get_server_actor_url as a generally useful method (just a visible alias to fetch something from configuration and double checking it is really a server actor)
• get_server_actor_openapi_spec to properly support 3

[vdusek]

open api specs need apify/apify-docs#3115

[Pijukatel]

Looks good to me.

Just an idea for consideration since this will be a new public way to work with server actors, we can carefully consider the options.

What if ServerActor would be a component of Actor? It would work a little bit around the name you are not sure about. Server Actor is clearly something different than normal Actor. Maybe we can make the distinction less blurry?
The methods and functionality related to the server would be nicely grouped together, not inflating the normal Actor.

So instead of
ActorClient.get_server_url
ActorClient.server_request
ActorClient.get_server_openapi_spec

You would get something like
ActorClient.server.get_url
ActorClient.server.request
ActorClient.server.get_openapi_spec