@spec authenticate(Wiki.Action.Session.t(), String.t(), String.t()) ::
  Wiki.Action.Session.result()

Make requests to authenticate a client session. This should only be done using a bot username and password, which can be created for any normal user account.

Arguments

• session - Base session pointing to a wiki.
• username - Bot username, may be different than the final logged-in username.
• password - Bot password. Protect this string, it allows others to take on-wiki actions on your behalf.

Return value

Authenticated session object.

@spec authenticate!(Wiki.Action.Session.t(), String.t(), String.t()) ::
  Wiki.Action.Session.t()

Assertive variant of authenticate

@spec get(
  Wiki.Action.Session.t(),
  keyword()
) :: Wiki.Action.Session.result()

Make an API GET request

Arguments

• session - Wiki.Action.Session object.
• params - Keyword list of query parameters as atoms or strings.

Return value

Session object with its .result populated.

@spec get!(
  Wiki.Action.Session.t(),
  keyword()
) :: Wiki.Action.Session.t()

Assertive variant of get.

@spec get_token(Wiki.Action.Session.t(), atom()) ::
  {:ok, Wiki.Action.Session.t(), token :: binary()} | {:error, any()}

Helper to make a token request

The Action API requires various tokens for login, edit actions, and so on. This function simplifies the request.

TODO: support multiple atoms

@spec new(site_action_handle(), client_options()) :: Wiki.Action.Session.t()

Create a new client session

Arguments

• site - target wiki and its action endpoint
• opts - configuration options which modify client behavior

Examples

Connect to German Wikipedia:

api = Wiki.Action.new(:dewiki)

Connect to a local development wiki:

api = Wiki.Action.new("http://dev.wiki.local.wmftest.net:8080/w/api.php")

@spec post(
  Wiki.Action.Session.t(),
  keyword()
) :: Wiki.Action.Session.result()

Make an API POST request.

Arguments

• session - Wiki.Action.Session object. If credentials are required for this action, you should have created this object with the authenticate/3 function.
• params - Keyword list of query parameters as atoms or strings.

Return value

Session object with a populated :result attribute.

@spec post!(
  Wiki.Action.Session.t(),
  keyword()
) :: Wiki.Action.Session.t()

Assertive variant of post.

@spec stream(
  Wiki.Action.Session.t(),
  keyword()
) :: Enumerable.t()

Make a GET request and follow continuations until exhausted or the stream is closed.

Arguments

• session - Wiki.Action.Session object.
• params - Keyword list of query parameters as atoms or strings.

Return value

Enumerable Stream, where each returned chunk is a raw result map, possibly containing multiple records. This corresponds to session.result from the other entry points.

@spec upload(Wiki.Action.Session.t(), binary(), keyword()) ::
  Wiki.Action.Session.result()

Upload a file from a local path

Request

authed_api |> Wiki.Action.upload("/tmp/Triops_closeup.jpg")

Response

{:ok, %Wiki.Action.Session{
  ...
  result: %{
    "upload" => %{
      "filename" => "Triops_closeup.jpg",
      "imageinfo" => %{
        "bitdepth" => 8,
        "canonicaltitle" => "File:Triops closeup.jpg",
        "comment" => "",
        "commonmetadata" => [
          %{
            "name" => "Copyright",
            "value" => [%{"name" => 0, "value" => "Karsten Grabow"}]
          },
          %{
            "name" => "JPEGFileComment",
            "value" => [%{"name" => 0, "value" => "Copyright Karsten Grabow"}]
          }
        ],
        "descriptionurl" => "http://dev.wiki.local.wmftest.net:8080/wiki/File:Triops_closeup.jpg",
        "extmetadata" => %{
          "DateTime" => %{
            "hidden" => "",
            "source" => "mediawiki-metadata",
            "value" => "2025-11-07T21:31:17Z"
          },
          "ObjectName" => %{
            "source" => "mediawiki-metadata",
            "value" => "Triops closeup"
          }
        },
        "height" => 827,
        "html" => "..."
        "mediatype" => "BITMAP",
        "metadata" => [
          %{
            "name" => "Copyright",
            "value" => [%{"name" => 0, "value" => "Karsten Grabow"}]
          },
          %{
            "name" => "JPEGFileComment",
            "value" => [%{"name" => 0, "value" => "Copyright Karsten Grabow"}]
          },
          %{"name" => "MEDIAWIKI_EXIF_VERSION", "value" => 2}
        ],
        "mime" => "image/jpeg",
        "parsedcomment" => "",
        "sha1" => "12ce3375983eb929fba91bf5267ad932929e9217",
        "size" => 222944,
        "timestamp" => "2025-11-07T21:31:17Z",
        "url" => "http://dev.wiki.local.wmftest.net:8080/w/images/4/45/Triops_closeup.jpg",
        "user" => "Admin",
        "userid" => 2,
        "width" => 1280
      },
      "result" => "Success"
    }
  },
}}

Upload with additional parameters:

authed_api |> Wiki.Action.upload(
  "/tmp/Test.jpg",
  text: "This is a test file",
  comment: "Upload initial draft from Elixir",
  ignorewarnings: true
)

@spec upload_file_content(
  Wiki.Action.Session.t(),
  filename :: binary(),
  content :: binary() | Enumerable.t(),
  keyword()
) :: Wiki.Action.Session.result()

Upload a file with content passed directly, as binary or a stream