Using Confluence Python API

[Erik Brown]

I'm trying to get started with the python API for our cloud instance and am having some issues. I can't seem to find a simple example anywhere so thought I would lay this out with some details and hope for some insight.

API is here: https://atlassian-python-api.readthedocs.io/

I have a token created from: https://id.atlassian.com/manage-profile/security/api-tokens

My token has a token-label and a token-string.

First question: what's the right way to instantiate a Confluence object.  Should the site URL include the "/wiki" to represent confluence or not? Do I use the token label and string, or do I use my email and token string?

confluence = Confluence(
    url='https://my-site.atlassian.net/wiki',  # with or without /wiki?
    username="my-email",   # is this my email or my token label?
    password="token-string",
    cloud=True)

Second question: what is the right way to reference a space and a page.  I have a space named "Company Information" and a first-level page called "Company Tools" and I just want to see if the page exists. The following code always returns false, however, so something is amiss.  Interestingly, I get false returned her if I pass my token label as "username" into the above constructor; and an ApiPermissionError if I pass in my email.

# What are the right parameters for this function?
if confluence.page_exists("Company Information", "Company Tools"):
    print("page exists")
else:
    print("page not found"

Third question: my final attempt was to get the set of spaces in Confluence.  I am an administrator so you'd think I would have access.  With the token label, I get an error here.  With my email, I get an array, but my print statement prints some labels that doesn't make any sense to me.  Is there a way to get more details specs on these commands?

# Just trying to print out all the spaces available to me
spaces = confluence.get_all_spaces(start=0, limit=500, expand=None)
for s in spaces:
    print(s

If there is a good reference for such questions, I would greatly appreciate it.  The documentation seems rather lax (or I'm just not finding it).

Thanks,

Erik

[Erik Brown · Accepted solution]

Thank you, @Hana Kučerová , very helpful.  I've been playing around with this in the console for a bit.  I'm not sure why Atlassian doesn't create some real documentation for these, but perhaps this will help someone else in the future.

I think I've been able to put together the answers:

1. For the Confluence constructor: You can use your URL with or without the '/wiki' - both seem to work.  You pass in your email address and the generated api token string.
2. For "space" they really mean "space key" as Hana indicated.  So if the key for the "Company Information" page is "CI" then you would call this as follows:
   

   confluence.page_exists("CI", "Company Tools"

3. Finally, the return types are poorly defined, but using the type() function in the console gave some insight. The following call returns a dict object
   

   spaces = confluence.get_all_spaces(start=0, limit=500, expand=None)

   To get the actual spaces you need to reference spaces['results'] which returns another dict object of space information. After some experimentation, the following code seems to do the trick to print out the spaces in Confluence.

   spaces = confluence.get_all_spaces(start=0, limit=500, expand=None)
   slist = spaces['results']
   for s in slist:
       print(s['key'], s['name'], s['type'])

The examples Hana pointed to in the GitHub repo are helpful as well.

https://github.com/atlassian-api/atlassian-python-api/tree/master/examples/confluence

Thanks again, @Hana Kučerová , for the prompt reply and pointing me in the right direction.

Erik

[Hana Kučerová]

Hi @Erik Brown ,

I'm happy to help.

Just to avoid confussion in the future - this library is not developed and supported by Atlassian.

[LORD]

1. confluence = Confluence(
   url='https://my-site.atlassian.net/wiki', # with or without /wiki?
   username="my-email", # is this my email or my token label?
   password="token-string",
   cloud=True)
   

# What are the right parameters for this function?
if confluence.page_exists("Company Information", "Company Tools"):
    print("page exists")
else:
    print("page not found"
 

# Just trying to print out all the spaces available to me
spaces = confluence.get_all_spaces(start=0, limit=500, expand=None)
for s in spaces:
    print(s
confluence.page_exists("CI", "Company Tools"
spaces = confluence.get_all_spaces(start=0, limit=500, expand=None)
spaces = confluence.get_all_spaces(start=0, limit=500, expand=None)

slist = spaces['results']

for s in slist:

    print(s['key'], s['name'], s['type'])

[Hana Kučerová]

Hi @Erik Brown ,

I don't have any experience with python API, but I work a lot with REST API, so hopefuly I will be able to help you. 

1) I believe the right combination is: https://my-site.atlassian.net/wiki, your email, token, True  

2) I would expect parameters space key and page id instead of space name and page title. Are you able to determine, whether strings or numbers are expected as params? Are you able to get more detailed error message for ApiPermissionError?

3) It looks like one of the maintainters is @Gonchik Tsymzhitov , who is active member of this community, so hopefully he will be able to provide you with more detailed documentation or help in general :-). I hope he doesn't mind I've mentioned him here.

[Hana Kučerová]

2) I looked into the code and it looks like space key and page title is expected. So please try to replace space name with space key.

[Hana Kučerová]

Also, maybe these examples can help you.

[Robert Gottesman]

Just a guess, but you should check the space permissions of the space with the email address used in the API. 

Your setup for question #1 is correct where you need to use the user's email address.  The examples Hana stated above should answer most of your questions.